# mulesoft Omni Gateway - Full Documentation

<!-- document id=4ebe52dda26dbd7001d24fa024a8222326ef9a9e68ac92b8c60dcdd4ddb77ba8 url=/mulesoft/current/en-us/gateway/1.12/policies-included-a2a-agent-card.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Agent Card Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Agent Card</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rewrites the Agent Card URL to match the public URL of the gateway</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Agent Card Policy rewrites the URL in the A2A Agent Card responses so that the exposed URL
points to the public endpoint of the Flex Gateway A2A server instance rather than directly to
backend services. This ensures that all client requests are routed through Flex Gateway, enabling it
to enforce security and access controls, while preventing direct access to backend resources.

The A2A Agent Card policy also enables the **Total Agent Calls** metric that tracks the total
successful and unsuccessful calls made to the agent. To view **Total Agent Calls**, see
[Viewing Key Metrics in API Manager for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-api-metrics).

## Configuring Policy Parameters

### Flex Gateway Local Mode

The A2A Agent Card policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Consumer URL</p></div></div></td><td><div><div><p>The consumer URL of the agent’s A2A service where JSON-RPC requests are sent.<br>If the consumer URL isn’t set, the server instance’s public endpoint is used.</p></div></div></td></tr><tr><td><div><div><p>Card Path</p></div></div></td><td><div><div><p>The path where the agent presents the card.</p></div></div></td></tr></tbody></table>

<!-- document id=a8a0ae3acdd158b9b2595bfd451f5aaa9ff28e9c6d0af2b4f38b4021c68bfeb7 url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-agent-card.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Agent Card Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Agent Card</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rewrites the Agent Card URL to match the public URL of the gateway</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-agent-card-release-notes">A2A Agent Card</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Agent Card Policy rewrites the URL in the A2A Agent Card responses so that the exposed URL
points to the public endpoint of the Omni Gateway A2A server instance rather than directly to
backend services. This ensures that all client requests are routed through Omni Gateway, enabling it
to enforce security and access controls, while preventing direct access to backend resources.

The A2A Agent Card policy also enables the **Total Agent Calls** metric that tracks the total
successful and unsuccessful calls made to the agent. To view **Total Agent Calls**, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-view-api-metrics).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Agent Card policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Consumer URL</p></div></div></td><td><div><div><p>The consumer URL of the agent’s A2A service where JSON-RPC requests are sent.<br>If the consumer URL isn’t set, the server instance’s public endpoint is used.</p></div></div></td></tr><tr><td><div><div><p>Card Path</p></div></div></td><td><div><div><p>The path where the agent presents the card.</p></div></div></td></tr></tbody></table>

<!-- document id=33e1835caab69978bc145c11ad09d9e4d1be9831ff545c12753100fe0a643322 url=/mulesoft/current/en-us/gateway/1.9/policies-included-a2a-agent-card.md -->

---
product: Omni Gateway
version: 1.9
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Agent Card Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Agent Card</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rewrites the Agent Card URL to match the public URL of the gateway</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Agent Card Policy rewrites the URL in the A2A Agent Card responses so that the exposed URL
points to the public endpoint of the Flex Gateway A2A server instance rather than directly to
backend services. This ensures that all client requests are routed through Flex Gateway, enabling it
to enforce security and access controls, while preventing direct access to backend resources.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The A2A Agent Card policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Consumer URL</p></div></div></td><td><div><div><p>The consumer URL of the agent’s A2A service where JSON-RPC requests are sent.<br>If the consumer URL isn’t set, the server instance’s public endpoint is used.</p></div></div></td></tr><tr><td><div><div><p>Card Path</p></div></div></td><td><div><div><p>The path where the agent presents the card.</p></div></div></td></tr></tbody></table>

<!-- document id=4b78d658d14e89c58677d4f0a47367594914a5fc4585c01a26abaa21b3556d1e url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-agent-card.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Agent Card Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Agent Card</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rewrites the Agent Card URL to match the public URL of the gateway</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-agent-card-release-notes">A2A Agent Card</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Agent Card Policy rewrites the URL in the A2A Agent Card responses so that the exposed URL
points to the public endpoint of the Omni Gateway A2A server instance rather than directly to
backend services. This ensures that all client requests are routed through Omni Gateway, enabling it
to enforce security and access controls, while preventing direct access to backend resources.

The A2A Agent Card policy also enables the **Total Agent Calls** metric that tracks the total
successful and unsuccessful calls made to the agent. To view **Total Agent Calls**, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-view-api-metrics).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Agent Card policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Consumer URL</p></div></div></td><td><div><div><p>The consumer URL of the agent’s A2A service where JSON-RPC requests are sent.<br>If the consumer URL isn’t set, the server instance’s public endpoint is used.</p></div></div></td></tr><tr><td><div><div><p>Card Path</p></div></div></td><td><div><div><p>The path where the agent presents the card.</p></div></div></td></tr></tbody></table>

<!-- document id=a59586a91f1e52b91c5b6128ba619b88132a43290f4ce583aad1178516d6553c url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-a2a-intask-authorization-code.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, a2a, authentication, oauth2, outbound
---

# A2A In-Task Authorization Code Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A In-Task Authorization Code</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.11.4</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>200 (authentication challenge), 401 (authentication failure)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The In-Task Authorization Code policy is an outbound policy that ensures secondary credentials are
present for in-task authentication using OAuth 2.0 Authorization Code flow. When requests require
additional authentication beyond the initial connection, this policy:

1.  Detects if a request contains a secondary authentication token at
    `$.params.message.parts[].data.auth_credentials.accessToken`. This policy assumes that all
    requests besides agent card requests require secondary authentication.

2.  If a secondary token is missing, the policy returns an `auth-required` challenge with details of
    where the agent can obtain the token from the OAuth 2.0 authentication provider.

    To learn more about the authentication challenge response, see
    [Challenge Response Format](#challenge-response).

3.  If the token was initially provided or returned from the challenge response, the policy extracts
    the token from the request body.

4.  The policy sets the extracted token in the `Authorization` header and removes the token from the
    request body to prevent token leakage.

    To learn more about token handling, see [Token Handling](#token-handling).

5.  The policy then forwards the request to upstream services.

When the inbound user can be identified, the policy reuses secondary tokens from a token cache. To
learn more about how this policy caches requests, see [Token caching](#token-caching-intask).

> [!NOTE] To ensure agent discovery works uninterrupted, requests to these agent card endpoints
> bypass the policy without authentication:
>
> - `/.well-known/agent-card.json`
>
> - Any path ending in `agent-card.json`

## Configuring Policy Parameters

### Flex Gateway Local Mode

The In-Task Authorization Code policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Secondary Auth Provider</p></div></div></td><td><div><div><p>Name of the OAuth 2.0 identity provider. For example: <code>okta</code>, <code>azure-ad</code>, <code>auth0</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Authorization Endpoint</p></div></div></td><td><div><div><p>Authorization endpoint URL of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/authorize</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>Token endpoint of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/token</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Scopes</p></div></div></td><td><div><div><p>Space or comma separated list of the OAuth 2.0 scopes required for in-task authentication. For example: <code>openid profile email transaction:execute</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Redirect URI</p></div></div></td><td><div><div><p>OAuth 2.0 redirect URI that the client uses in the authorization flow.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Audience</p></div></div></td><td><div><div><p>OAuth 2.0 token audience. The intended recipient of the token. For example: <code>https://my-agent.example.com/api</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Response Type</p></div></div></td><td><div><div><p>OAuth 2.0 response type. Typically <code>code</code> for authorization code flow.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Code Challenge Method</p></div></div></td><td><div><div><p>PKCE code challenge method. Typically <code>S256</code> for SHA-256.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Body Encoding</p></div></div></td><td><div><div><p>Encoding format for token request body. Typically <code>form</code> for <code>application/x-www-form-urlencoded</code>. Default: <code>form</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Token Timeout</p></div></div></td><td><div><div><p>Timeout in seconds for token requests.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Challenge Response Status Code</p></div></div></td><td><div><div><p>HTTP status code to return for <code>auth-required</code> challenge responses. Typically <code>200</code> to maintain JSON-RPC compatibility.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache is shared across Flex Gateway replicas. Enable this option when running more than one replica to avoid duplicate token requests or repeated auth challenges.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr></tbody></table>

## Token Handling

For `GET` and `POST` requests, the policy handles the token differently:

- **GET**: The policy removes the request body after the token extraction.

- **POST**: The policy removes only the token property from the body and preserves the rest of the
  body.

The token is always removed from the body after extraction to prevent token leakage to the upstream
service. The extracted token is set in the `Authorization` header as the `Bearer <token>` before
forwarding the request. This overrides any existing `Authorization` header. Perform any
authentication of the first authorization header prior to this policy.

The policy extracts the token from `$.params.message.parts[].data.auth_credentials.accessToken`. For
example, using the default JSONPath, the policy extracts the token
(`"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…​"`) from the following request body:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "method": "message/send",
  "params": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "data",
          "data": {
            "auth_credentials": {
              "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
            }
          }
        }
      ]
    }
  }
}
```

## Challenge Response Format

If no secondary authentication token is found, the policy returns an `auth-required` A2A task
response. The response preserves the `taskId` and `contextId` from the request if originally
provided:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "result": {
    "id": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "auth-required",
      "message": {
        "kind": "message",
        "role": "agent",
        "messageId": "msg-abc123",
        "taskId": "task-123",
        "parts": [
          {
            "kind": "text",
            "text": "To continue this task, additional authorization is required."
          },
          {
            "kind": "data",
            "data": {
              "authChallenge": {
                "secondaryAuthProvider": "okta",
                "authorizationEndpoint": "https://dev-12345.okta.com/oauth2/v1/authorize",
                "tokenEndpoint": "https://dev-12345.okta.com/oauth2/v1/token",
                "scopes": ["openid", "profile", "email"],
                "audience": "https://my-agent.example.com/api",
                "redirectUri": "https://myapp.example.com/oauth/callback",
                "responseType": "code",
                "codeChallengeMethod": "S256",
                "bodyEncoding": "form"
              }
            }
          }
        ],
        "metadata": {}
      },
      "timestamp": "2025-01-01T00:00:00.000Z"
    },
    "kind": "task"
  }
}
```

## Token caching

When the request body includes a secondary access token, the policy stores it for later reuse. When
the body doesn’t include a token, the policy tries the cache before returning an `auth-required`
challenge:

- The cache is keyed per user and is derived from the bearer JWT in the inbound `Authorization`
  header. The policy uses the first available of the `sub`, `email`, `azp`, or OAuth client
  identifier claims. If that JWT can’t be parsed or none of these claims is present, the policy does
  not cache or reuse tokens.

- Cache entry lifetime is derived from the token timeout. When a token expires, it’s discarded from
  the cache.

## See Also

- [Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-outbound-directory)

- [Credential Injection OAuth 2.0](https://docs.mulesoft.com/gateway/1.12/policies-outbound-oauth)

- [A2A Agent Card Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-agent-card)

- [A2A Schema Validation Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-schema-validation)

<!-- document id=8d0fd9686a48651d391510b3d539d80760a8c808288a63c0d04772c6771b85d2 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-a2a-intask-authorization-code.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, a2a, authentication, oauth2, outbound
---

# A2A In-Task Authorization Code Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A In-Task Authorization Code</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.4</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-intask-authorization-code-policy-release-notes">A2A In-Task Authorization Code Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>200 (authentication challenge), 401 (authentication failure)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The In-Task Authorization Code policy is an outbound policy that ensures secondary credentials are
present for in-task authentication using OAuth 2.0 Authorization Code flow. When requests require
additional authentication beyond the initial connection, this policy:

1.  Detects if a request contains a secondary authentication token at
    `$.params.message.parts[].data.auth_credentials.accessToken`. This policy assumes that all
    requests besides agent card requests require secondary authentication.

2.  If a secondary token is missing, the policy returns an `auth-required` challenge with details of
    where the agent can obtain the token from the OAuth 2.0 authentication provider.

    To learn more about the authentication challenge response, see
    [Challenge Response Format](#challenge-response).

3.  If the token was initially provided or returned from the challenge response, the policy extracts
    the token from the request body.

4.  The policy sets the extracted token in the `Authorization` header and removes the token from the
    request body to prevent token leakage.

    To learn more about token handling, see [Token Handling](#token-handling).

5.  The policy then forwards the request to upstream services.

When the inbound user can be identified, the policy reuses secondary tokens from a token cache. To
learn more about how this policy caches requests, see [Token caching](#token-caching-intask).

> [!NOTE] To ensure agent discovery works uninterrupted, requests to these agent card endpoints
> bypass the policy without authentication:
>
> - `/.well-known/agent-card.json`
>
> - Any path ending in `agent-card.json`

## Configuring Policy Parameters

### Omni Gateway Local Mode

The In-Task Authorization Code policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Secondary Auth Provider</p></div></div></td><td><div><div><p>Name of the OAuth 2.0 identity provider. For example: <code>okta</code>, <code>azure-ad</code>, <code>auth0</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Authorization Endpoint</p></div></div></td><td><div><div><p>Authorization endpoint URL of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/authorize</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>Token endpoint of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/token</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Scopes</p></div></div></td><td><div><div><p>Space or comma separated list of the OAuth 2.0 scopes required for in-task authentication. For example: <code>openid profile email transaction:execute</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Redirect URI</p></div></div></td><td><div><div><p>OAuth 2.0 redirect URI that the client uses in the authorization flow.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Audience</p></div></div></td><td><div><div><p>OAuth 2.0 token audience. The intended recipient of the token. For example: <code>https://my-agent.example.com/api</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Response Type</p></div></div></td><td><div><div><p>OAuth 2.0 response type. Typically <code>code</code> for authorization code flow.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Code Challenge Method</p></div></div></td><td><div><div><p>PKCE code challenge method. Typically <code>S256</code> for SHA-256.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Body Encoding</p></div></div></td><td><div><div><p>Encoding format for token request body. Typically <code>form</code> for <code>application/x-www-form-urlencoded</code>. Default: <code>form</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Token Timeout</p></div></div></td><td><div><div><p>Timeout in seconds for token requests.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Challenge Response Status Code</p></div></div></td><td><div><div><p>HTTP status code to return for <code>auth-required</code> challenge responses. Typically <code>200</code> to maintain JSON-RPC compatibility.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache is shared across Omni Gateway replicas. Enable this option when running more than one replica to avoid duplicate token requests or repeated auth challenges.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr></tbody></table>

## Token Handling

For `GET` and `POST` requests, the policy handles the token differently:

- **GET**: The policy removes the request body after the token extraction.

- **POST**: The policy removes only the token property from the body and preserves the rest of the
  body.

The token is always removed from the body after extraction to prevent token leakage to the upstream
service. The extracted token is set in the `Authorization` header as the `Bearer <token>` before
forwarding the request. This overrides any existing `Authorization` header. Perform any
authentication of the first authorization header prior to this policy.

The policy extracts the token from `$.params.message.parts[].data.auth_credentials.accessToken`. For
example, using the default JSONPath, the policy extracts the token
(`"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…​"`) from the following request body:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "method": "message/send",
  "params": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "data",
          "data": {
            "auth_credentials": {
              "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
            }
          }
        }
      ]
    }
  }
}
```

## Challenge Response Format

If no secondary authentication token is found, the policy returns an `auth-required` A2A task
response. The response preserves the `taskId` and `contextId` from the request if originally
provided:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "result": {
    "id": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "auth-required",
      "message": {
        "kind": "message",
        "role": "agent",
        "messageId": "msg-abc123",
        "taskId": "task-123",
        "parts": [
          {
            "kind": "text",
            "text": "To continue this task, additional authorization is required."
          },
          {
            "kind": "data",
            "data": {
              "authChallenge": {
                "secondaryAuthProvider": "okta",
                "authorizationEndpoint": "https://dev-12345.okta.com/oauth2/v1/authorize",
                "tokenEndpoint": "https://dev-12345.okta.com/oauth2/v1/token",
                "scopes": ["openid", "profile", "email"],
                "audience": "https://my-agent.example.com/api",
                "redirectUri": "https://myapp.example.com/oauth/callback",
                "responseType": "code",
                "codeChallengeMethod": "S256",
                "bodyEncoding": "form"
              }
            }
          }
        ],
        "metadata": {}
      },
      "timestamp": "2025-01-01T00:00:00.000Z"
    },
    "kind": "task"
  }
}
```

## Token caching

When the request body includes a secondary access token, the policy stores it for later reuse. When
the body doesn’t include a token, the policy tries the cache before returning an `auth-required`
challenge:

- The cache is keyed per user and is derived from the bearer JWT in the inbound `Authorization`
  header. The policy uses the first available of the `sub`, `email`, `azp`, or OAuth client
  identifier claims. If that JWT can’t be parsed or none of these claims is present, the policy does
  not cache or reuse tokens.

- Cache entry lifetime is derived from the token timeout. When a token expires, it’s discarded from
  the cache.

## See Also

- [Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-outbound-directory)

- [Credential Injection OAuth 2.0](https://docs.mulesoft.com/gateway/1.13/policies-outbound-oauth)

- [A2A Agent Card Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-agent-card)

- [A2A Schema Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-schema-validation)

<!-- document id=bcc0704c1f2c12a804f0552d6181c18a109f290a54c8b58a3617971393eb369b url=/mulesoft/current/en-us/gateway/latest/policies-outbound-a2a-intask-authorization-code.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, a2a, authentication, oauth2, outbound
---

# A2A In-Task Authorization Code Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A In-Task Authorization Code</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.4</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-intask-authorization-code-policy-release-notes">A2A In-Task Authorization Code Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>200 (authentication challenge), 401 (authentication failure)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The In-Task Authorization Code policy is an outbound policy that ensures secondary credentials are
present for in-task authentication using OAuth 2.0 Authorization Code flow. When requests require
additional authentication beyond the initial connection, this policy:

1.  Detects if a request contains a secondary authentication token at
    `$.params.message.parts[].data.auth_credentials.accessToken`. This policy assumes that all
    requests besides agent card requests require secondary authentication.

2.  If a secondary token is missing, the policy returns an `auth-required` challenge with details of
    where the agent can obtain the token from the OAuth 2.0 authentication provider.

    To learn more about the authentication challenge response, see
    [Challenge Response Format](#challenge-response).

3.  If the token was initially provided or returned from the challenge response, the policy extracts
    the token from the request body.

4.  The policy sets the extracted token in the `Authorization` header and removes the token from the
    request body to prevent token leakage.

    To learn more about token handling, see [Token Handling](#token-handling).

5.  The policy then forwards the request to upstream services.

When the inbound user can be identified, the policy reuses secondary tokens from a token cache. To
learn more about how this policy caches requests, see [Token caching](#token-caching-intask).

> [!NOTE] To ensure agent discovery works uninterrupted, requests to these agent card endpoints
> bypass the policy without authentication:
>
> - `/.well-known/agent-card.json`
>
> - Any path ending in `agent-card.json`

## Configuring Policy Parameters

### Omni Gateway Local Mode

The In-Task Authorization Code policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Secondary Auth Provider</p></div></div></td><td><div><div><p>Name of the OAuth 2.0 identity provider. For example: <code>okta</code>, <code>azure-ad</code>, <code>auth0</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Authorization Endpoint</p></div></div></td><td><div><div><p>Authorization endpoint URL of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/authorize</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>Token endpoint of the OAuth 2.0 service. For example: <code>https://dev-12345.okta.com/oauth2/v1/token</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Scopes</p></div></div></td><td><div><div><p>Space or comma separated list of the OAuth 2.0 scopes required for in-task authentication. For example: <code>openid profile email transaction:execute</code>.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Redirect URI</p></div></div></td><td><div><div><p>OAuth 2.0 redirect URI that the client uses in the authorization flow.</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p>Token Audience</p></div></div></td><td><div><div><p>OAuth 2.0 token audience. The intended recipient of the token. For example: <code>https://my-agent.example.com/api</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Response Type</p></div></div></td><td><div><div><p>OAuth 2.0 response type. Typically <code>code</code> for authorization code flow.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Code Challenge Method</p></div></div></td><td><div><div><p>PKCE code challenge method. Typically <code>S256</code> for SHA-256.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Body Encoding</p></div></div></td><td><div><div><p>Encoding format for token request body. Typically <code>form</code> for <code>application/x-www-form-urlencoded</code>. Default: <code>form</code>.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Token Timeout</p></div></div></td><td><div><div><p>Timeout in seconds for token requests.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Challenge Response Status Code</p></div></div></td><td><div><div><p>HTTP status code to return for <code>auth-required</code> challenge responses. Typically <code>200</code> to maintain JSON-RPC compatibility.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache is shared across Omni Gateway replicas. Enable this option when running more than one replica to avoid duplicate token requests or repeated auth challenges.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr></tbody></table>

## Token Handling

For `GET` and `POST` requests, the policy handles the token differently:

- **GET**: The policy removes the request body after the token extraction.

- **POST**: The policy removes only the token property from the body and preserves the rest of the
  body.

The token is always removed from the body after extraction to prevent token leakage to the upstream
service. The extracted token is set in the `Authorization` header as the `Bearer <token>` before
forwarding the request. This overrides any existing `Authorization` header. Perform any
authentication of the first authorization header prior to this policy.

The policy extracts the token from `$.params.message.parts[].data.auth_credentials.accessToken`. For
example, using the default JSONPath, the policy extracts the token
(`"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…​"`) from the following request body:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "method": "message/send",
  "params": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "data",
          "data": {
            "auth_credentials": {
              "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
            }
          }
        }
      ]
    }
  }
}
```

## Challenge Response Format

If no secondary authentication token is found, the policy returns an `auth-required` A2A task
response. The response preserves the `taskId` and `contextId` from the request if originally
provided:

```json
{
  "jsonrpc": "2.0",
  "id": "req-18",
  "result": {
    "id": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "auth-required",
      "message": {
        "kind": "message",
        "role": "agent",
        "messageId": "msg-abc123",
        "taskId": "task-123",
        "parts": [
          {
            "kind": "text",
            "text": "To continue this task, additional authorization is required."
          },
          {
            "kind": "data",
            "data": {
              "authChallenge": {
                "secondaryAuthProvider": "okta",
                "authorizationEndpoint": "https://dev-12345.okta.com/oauth2/v1/authorize",
                "tokenEndpoint": "https://dev-12345.okta.com/oauth2/v1/token",
                "scopes": ["openid", "profile", "email"],
                "audience": "https://my-agent.example.com/api",
                "redirectUri": "https://myapp.example.com/oauth/callback",
                "responseType": "code",
                "codeChallengeMethod": "S256",
                "bodyEncoding": "form"
              }
            }
          }
        ],
        "metadata": {}
      },
      "timestamp": "2025-01-01T00:00:00.000Z"
    },
    "kind": "task"
  }
}
```

## Token caching

When the request body includes a secondary access token, the policy stores it for later reuse. When
the body doesn’t include a token, the policy tries the cache before returning an `auth-required`
challenge:

- The cache is keyed per user and is derived from the bearer JWT in the inbound `Authorization`
  header. The policy uses the first available of the `sub`, `email`, `azp`, or OAuth client
  identifier claims. If that JWT can’t be parsed or none of these claims is present, the policy does
  not cache or reuse tokens.

- Cache entry lifetime is derived from the token timeout. When a token expires, it’s discarded from
  the cache.

## See Also

- [Outbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-outbound-directory)

- [Credential Injection OAuth 2.0](https://docs.mulesoft.com/gateway/latest/policies-outbound-oauth)

- [A2A Agent Card Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-agent-card)

- [A2A Schema Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-schema-validation)

<!-- document id=fac42f116751209071c5eda568e496a35b4237c2afedc4b8a7b6f5f432cba82d url=/mulesoft/current/en-us/gateway/1.12/policies-included-a2a-pii-detector.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Personally Identifiable Information (PII) Detector Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A PII Detector Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A PII Detector policy detects personally identifiable information (PII) in requests sent to
the agent. If PII is detected, you can either log or block the request. A policy violation is always
reported if PII is detected.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The A2A PII Detector policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Entities</p></div></div></td><td><div><div><p>Array that defines the types of PII to detect. You can select multiple PII types. Supported values are <code>Email</code>, <code>US SSN</code>, <code>Credit Card</code>, <code>Phone Number</code>.<br>For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>Action to take when PII is detected. Supported values are <code>Log</code> or <code>Block</code>.</p></div></div></td></tr></tbody></table>

### PII Types

When you configure an A2A PII Detector policy, you can choose which types of PII to detect.

The following table describes the type of PII this policy can detect:

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code></p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs) in the standard format: <code>XXX-XX-XXXX</code> where each <code>X</code> is a digit. For example: <code>123-45-6789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers in the form of four groups of four digits, separated by optional spaces or hyphens. Examples: <code>1234-5678-9012-3456</code>, <code>1234 5678 9012 3456</code>, or <code>1234567890123456</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>United States phone numbers in various formats, with or without country code, parentheses, spaces, hyphens, or dots. Examples: <code>123-456-7890</code>, <code>(123) 456-7890</code>, <code>123.456.7890</code>, <code>+1 123 456 7890</code>, or <code>1234567890</code>.</p></div></div></td></tr></tbody></table>

<!-- document id=8f3e6464f93a8eb5f2101f900cea7a4f05f3e8a1e8e2ff03280be274b2389f3e url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-pii-detector.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Personally Identifiable Information (PII) Detector Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A PII Detector Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in A2A JSON-RPC traffic</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-pii-detector-release-notes">A2A PII Detector</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>HTTP 403 with JSON-RPC 2.0 error code <code>-32602</code> (Invalid params)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A PII Detector policy detects personally identifiable information (PII) in A2A JSON-RPC
traffic on both the request and response sides.

On the request side, if PII is detected, you can configure the policy to reject, log, or log masked
findings. On the response side, the policy scans and logs any PII detected but never rejects or
rewrites responses. A policy violation is reported when PII is detected.

The policy supports JSON-RPC over HTTP transport and returns HTTP 403 with error code `-32602` when
rejecting requests.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A PII Detector policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>PII Types</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Array of built-in PII types to detect. Supported values are <strong>Email</strong>, <strong>US SSN</strong>, <strong>Credit Card</strong>, and <strong>Phone Number</strong>. For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td></tr><tr><td><div><div><p>Custom PII Patterns</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Array of custom regex patterns to detect additional sensitive values. Define a name and regex pattern for each array entry. For example, use <code>name: AWS Access Key</code> and <code>pattern: AKIA[0-9A-Z]{16}</code> to detect AWS access keys.</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Action to take when PII is detected. Supported values are <strong>Reject</strong>, <strong>Log</strong>, and <strong>Log and mask</strong>. Default is <strong>Log</strong>.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The policy scans A2A JSON-RPC traffic for PII on both request and response sides.

### Request-Side Enforcement

The policy scans requests for these A2A JSON-RPC methods:

- `message/send`

- `message/stream`

- `tasks/get`

- `tasks/stream`

- `tasks/resubscribe`

For each request, the policy inspects these field paths in order:

1.  `params.message.parts[]` — scans each `text` JSON object

2.  `params.task.parts[]` — scans each `text` JSON object

3.  `params.task.description` — scans the string value

The policy stops scanning at the first PII detection and applies the configured action to the entire
request.

Based on the configured action:

- **Reject**: Blocks the request and returns HTTP 403 with a JSON-RPC 2.0 error response. The
  upstream never receives the request.

- **Log**: Forwards the request unchanged and logs findings with actual PII values.

- **Log and mask**: Forwards the request unchanged and logs findings with masked values.

### Response-Side Logging

On the response side, the policy scans both JSON responses and Server-Sent Events (SSE) streams:

- **JSON responses**: Scanned across multiple A2A result paths including
  `result.status.message.parts[].text`, `result.artifact.parts[].text`, `result.task.parts[].text`,
  `result.task.description`, and others.

- **SSE streams (text/event-stream)**: Each complete SSE event’s `data:` payload is scanned.

Response-side detections are always logged with raw PII values, regardless of the configured action.
Responses are never rejected or rewritten — they always pass through unchanged to the client.

The policy detects overlapping PII patterns and keeps the longest (most specific) match. For
example, a credit card number with delimiters that could also match an SSN pattern is detected as a
credit card.

## PII Types

When you configure the A2A PII Detector policy, choose which types of PII to detect.

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code>.</p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs), including formats with various delimiters such as <code>123-45-6789</code>, <code>123 45 6789</code>, <code>123.45.6789</code>, <code>123,45,6789</code>, <code>123/45/6789</code>, <code>123\45\6789</code>, or <code>123456789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers for Visa, MasterCard, American Express, and Discover, with or without separators. Examples: <code>4111-1111-1111-1111</code>, <code>4111 1111 1111 1111</code>, <code>4111111111111111</code>, <code>4111.1111.1111.1111</code>, <code>5500-0000-0000-0004</code>, <code>3782-822463-10005</code>, <code>6011-0000-0000-0004</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>Phone numbers in common domestic and international formats based on ITU E.164 country codes. Examples include US numbers like <code>(555) 123-4567</code>, <code>555-123-4567</code>, <code>+1-555-123-4567</code>, and international numbers like <code>+91 98765 43210</code>, <code>+44 20 7946 0958</code>, <code>+49 30 12345678</code>.</p></div></div></td></tr></tbody></table>

## Response on Reject

When the policy blocks a request, it returns HTTP 403 with a JSON-RPC 2.0 error response.

For PII detected in `params.message.parts` or `params.task.parts`:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Request contains PII data: US SSN: 123-45-6789"
  }
}
```

For PII detected in `params.task.description`:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Request contains PII data in task description: US SSN: 123-45-6789"
  }
}
```

> [!NOTE] The error code is `-32602` (Invalid params) to indicate a client-side validation error.
> The `data` field is a string containing the detection details, not an object.

## Example Request and Logging

This example shows an A2A request containing multiple PII types and the corresponding log output for
different action configurations:

```json
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": 1,
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789."
        }
      ]
    }
  }
}
```

- Log

- Log and Mask

- Reject

When the action is set to **Log**, the policy logs detect PII with the actual values:

```json
[accessLog] Request: `Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789.` has sensitive data: [
  {
    "pii_type": "Email",
    "value": "john.doe@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "value": "(555) 123-4567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "value": "123-45-6789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Log and mask**, the policy logs detect PII with masked values:

```json
[accessLog] Request: `Contact me at ****@example.com or call +1******567. My SSN is ***-**-*789.` has sensitive data: [
  {
    "pii_type": "Email",
    "masked_value": "****@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "masked_value": "+1******567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "masked_value": "***-**-*789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Reject**, the policy blocks the request and returns an HTTP 403 error
response. The upstream never receives the original request containing PII.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Request contains PII data: US SSN: 123-45-6789"
  }
}
```

### Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern in a request:

```json
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": 2,
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment"
        }
      ]
    }
  }
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy
logs:

```json
[accessLog] Request: `Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment` has sensitive data: [
  {
    "pii_type": "AWS Access Key",
    "value": "AKIAIOSFODNN7EXAMPLE",
    "start": 18,
    "end": 38
  }
]
```

## Response Logging Example

When PII is detected in a response, the policy always logs it with raw values and forwards the
response unchanged:

Response from upstream:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "task": {
      "description": "Process SSN 123-45-6789 for user john@example.com"
    }
  }
}
```

Log output (regardless of action configuration):

```json
[accessLog] Response: `Process SSN 123-45-6789 for user john@example.com` has sensitive data: [
  {
    "pii_type": "US SSN",
    "value": "123-45-6789",
    "start": 12,
    "end": 23
  },
  {
    "pii_type": "Email",
    "value": "john@example.com",
    "start": 33,
    "end": 49
  }
]
```

The response is forwarded to the client unchanged. The **Reject**, **Log**, and **Log and mask**
actions have no effect on response processing.

## Edge Cases

The policy passes through these without scanning:

- Non-POST requests

- Requests without a JSON Content-Type

- Bodies that don’t parse as JSON-RPC

- Methods not in scope (`SendMessage`, `SendStreamingMessage`, and other v1-style methods)

- Requests with missing or malformed `params`

- Empty text parts

- Parts with `kind` or `type` other than `"text"`

If a regex engine error occurs while scanning a single part, the error is logged and that part is
skipped, but remaining parts continue to be scanned.

## Compliance and Data Flow

These tables show where raw PII values appear based on the configured action.

### PII Detected in Request

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Request Body on Wire</th><th>Access Log</th></tr></thead><tbody><tr><td><p>Reject</p></td><td><p>Blocked (HTTP 403 error; raw values appear in error.data string)</p></td><td><p>No log emitted on reject</p></td></tr><tr><td><p>Log and mask</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Masked</p></td></tr><tr><td><p>Log</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Raw</p></td></tr></tbody></table>

### PII Detected in Response

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Response Body on Wire</th><th>Access Log</th></tr></thead><tbody><tr><td><p>Any (Reject, Log, Log and mask)</p></td><td><p>Pass-through (raw values flow to the client)</p></td><td><p>Raw</p></td></tr></tbody></table>

> [!IMPORTANT] For the A2A PII Detector policy, the **Log and mask** action only masks the access
> log, not the request body. Raw PII still flows to the upstream agent when using **Log** or **Log
> and mask** actions. Only **Reject** prevents PII from reaching the agent on the request side.

> [!IMPORTANT] Response-side detections are always logged with raw PII values and responses always
> pass through unchanged, regardless of the configured action. The policy never rejects or rewrites
> responses.

## See Also

- [MCP PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-pii-detector)

- [LLM PII Detection Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-llm-pii-detection)

<!-- document id=26722ebf680832d57f1433dea13c2aa9126c73d1d03c1d85dc30df89c45f0d42 url=/mulesoft/current/en-us/gateway/1.9/policies-included-a2a-pii-detector.md -->

---
product: Omni Gateway
version: 1.9
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Personally Identifiable Information (PII) Detector Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A PII Detector Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A PII Detector policy detects personally identifiable information (PII) in requests sent to
the agent. If PII is detected, you can either log or block the request. A policy violation is always
reported if PII is detected.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The A2A PII Detector policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Entities</p></div></div></td><td><div><div><p>Array that defines the types of PII to detect. You can select multiple PII types. Supported values are <code>Email</code>, <code>US SSN</code>, <code>Credit Card</code>, <code>Phone Number</code>.<br>For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>Action to take when PII is detected. Supported values are <code>Log</code> or <code>Block</code>.</p></div></div></td></tr></tbody></table>

### PII Types

When you configure an A2A PII Detector policy, you can choose which types of PII to detect.

The following table describes the type of PII this policy can detect:

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code></p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs) in the standard format: <code>XXX-XX-XXXX</code> where each <code>X</code> is a digit. For example: <code>123-45-6789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers in the form of four groups of four digits, separated by optional spaces or hyphens. Examples: <code>1234-5678-9012-3456</code>, <code>1234 5678 9012 3456</code>, or <code>1234567890123456</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>United States phone numbers in various formats, with or without country code, parentheses, spaces, hyphens, or dots. Examples: <code>123-456-7890</code>, <code>(123) 456-7890</code>, <code>123.456.7890</code>, <code>+1 123 456 7890</code>, or <code>1234567890</code>.</p></div></div></td></tr></tbody></table>

<!-- document id=95e465d207f01582d127a3708f12f465b495052eadc84d349b9c5e748c40b59e url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-pii-detector.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Personally Identifiable Information (PII) Detector Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A PII Detector Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in A2A JSON-RPC traffic</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-pii-detector-release-notes">A2A PII Detector</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>HTTP 403 with JSON-RPC 2.0 error code <code>-32602</code> (Invalid params)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A PII Detector policy detects personally identifiable information (PII) in A2A JSON-RPC
traffic on both the request and response sides.

On the request side, if PII is detected, you can configure the policy to reject, log, or log masked
findings. On the response side, the policy scans and logs any PII detected but never rejects or
rewrites responses. A policy violation is reported when PII is detected.

The policy supports JSON-RPC over HTTP transport and returns HTTP 403 with error code `-32602` when
rejecting requests.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A PII Detector policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>PII Types</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Array of built-in PII types to detect. Supported values are <strong>Email</strong>, <strong>US SSN</strong>, <strong>Credit Card</strong>, and <strong>Phone Number</strong>. For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td></tr><tr><td><div><div><p>Custom PII Patterns</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Array of custom regex patterns to detect additional sensitive values. Define a name and regex pattern for each array entry. For example, use <code>name: AWS Access Key</code> and <code>pattern: AKIA[0-9A-Z]{16}</code> to detect AWS access keys.</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Action to take when PII is detected. Supported values are <strong>Reject</strong>, <strong>Log</strong>, and <strong>Log and mask</strong>. Default is <strong>Log</strong>.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The policy scans A2A JSON-RPC traffic for PII on both request and response sides.

### Request-Side Enforcement

The policy scans requests for these A2A JSON-RPC methods:

- `message/send`

- `message/stream`

- `tasks/get`

- `tasks/stream`

- `tasks/resubscribe`

For each request, the policy inspects these field paths in order:

1.  `params.message.parts[]` — scans each `text` JSON object

2.  `params.task.parts[]` — scans each `text` JSON object

3.  `params.task.description` — scans the string value

The policy stops scanning at the first PII detection and applies the configured action to the entire
request.

Based on the configured action:

- **Reject**: Blocks the request and returns HTTP 403 with a JSON-RPC 2.0 error response. The
  upstream never receives the request.

- **Log**: Forwards the request unchanged and logs findings with actual PII values.

- **Log and mask**: Forwards the request unchanged and logs findings with masked values.

### Response-Side Logging

On the response side, the policy scans both JSON responses and Server-Sent Events (SSE) streams:

- **JSON responses**: Scanned across multiple A2A result paths including
  `result.status.message.parts[].text`, `result.artifact.parts[].text`, `result.task.parts[].text`,
  `result.task.description`, and others.

- **SSE streams (text/event-stream)**: Each complete SSE event’s `data:` payload is scanned.

Response-side detections are always logged with raw PII values, regardless of the configured action.
Responses are never rejected or rewritten — they always pass through unchanged to the client.

The policy detects overlapping PII patterns and keeps the longest (most specific) match. For
example, a credit card number with delimiters that could also match an SSN pattern is detected as a
credit card.

## PII Types

When you configure the A2A PII Detector policy, choose which types of PII to detect.

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code>.</p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs), including formats with various delimiters such as <code>123-45-6789</code>, <code>123 45 6789</code>, <code>123.45.6789</code>, <code>123,45,6789</code>, <code>123/45/6789</code>, <code>123\45\6789</code>, or <code>123456789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers for Visa, MasterCard, American Express, and Discover, with or without separators. Examples: <code>4111-1111-1111-1111</code>, <code>4111 1111 1111 1111</code>, <code>4111111111111111</code>, <code>4111.1111.1111.1111</code>, <code>5500-0000-0000-0004</code>, <code>3782-822463-10005</code>, <code>6011-0000-0000-0004</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>Phone numbers in common domestic and international formats based on ITU E.164 country codes. Examples include US numbers like <code>(555) 123-4567</code>, <code>555-123-4567</code>, <code>+1-555-123-4567</code>, and international numbers like <code>+91 98765 43210</code>, <code>+44 20 7946 0958</code>, <code>+49 30 12345678</code>.</p></div></div></td></tr></tbody></table>

## Response on Reject

When the policy blocks a request, it returns HTTP 403 with a JSON-RPC 2.0 error response.

For PII detected in `params.message.parts` or `params.task.parts`:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Request contains PII data: US SSN: 123-45-6789"
  }
}
```

For PII detected in `params.task.description`:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Request contains PII data in task description: US SSN: 123-45-6789"
  }
}
```

> [!NOTE] The error code is `-32602` (Invalid params) to indicate a client-side validation error.
> The `data` field is a string containing the detection details, not an object.

## Example Request and Logging

This example shows an A2A request containing multiple PII types and the corresponding log output for
different action configurations:

```json
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": 1,
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789."
        }
      ]
    }
  }
}
```

- Log

- Log and Mask

- Reject

When the action is set to **Log**, the policy logs detect PII with the actual values:

```json
[accessLog] Request: `Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789.` has sensitive data: [
  {
    "pii_type": "Email",
    "value": "john.doe@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "value": "(555) 123-4567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "value": "123-45-6789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Log and mask**, the policy logs detect PII with masked values:

```json
[accessLog] Request: `Contact me at ****@example.com or call +1******567. My SSN is ***-**-*789.` has sensitive data: [
  {
    "pii_type": "Email",
    "masked_value": "****@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "masked_value": "+1******567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "masked_value": "***-**-*789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Reject**, the policy blocks the request and returns an HTTP 403 error
response. The upstream never receives the original request containing PII.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Request contains PII data: US SSN: 123-45-6789"
  }
}
```

### Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern in a request:

```json
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": 2,
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment"
        }
      ]
    }
  }
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy
logs:

```json
[accessLog] Request: `Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment` has sensitive data: [
  {
    "pii_type": "AWS Access Key",
    "value": "AKIAIOSFODNN7EXAMPLE",
    "start": 18,
    "end": 38
  }
]
```

## Response Logging Example

When PII is detected in a response, the policy always logs it with raw values and forwards the
response unchanged:

Response from upstream:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "task": {
      "description": "Process SSN 123-45-6789 for user john@example.com"
    }
  }
}
```

Log output (regardless of action configuration):

```json
[accessLog] Response: `Process SSN 123-45-6789 for user john@example.com` has sensitive data: [
  {
    "pii_type": "US SSN",
    "value": "123-45-6789",
    "start": 12,
    "end": 23
  },
  {
    "pii_type": "Email",
    "value": "john@example.com",
    "start": 33,
    "end": 49
  }
]
```

The response is forwarded to the client unchanged. The **Reject**, **Log**, and **Log and mask**
actions have no effect on response processing.

## Edge Cases

The policy passes through these without scanning:

- Non-POST requests

- Requests without a JSON Content-Type

- Bodies that don’t parse as JSON-RPC

- Methods not in scope (`SendMessage`, `SendStreamingMessage`, and other v1-style methods)

- Requests with missing or malformed `params`

- Empty text parts

- Parts with `kind` or `type` other than `"text"`

If a regex engine error occurs while scanning a single part, the error is logged and that part is
skipped, but remaining parts continue to be scanned.

## Compliance and Data Flow

These tables show where raw PII values appear based on the configured action.

### PII Detected in Request

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Request Body on Wire</th><th>Access Log</th></tr></thead><tbody><tr><td><p>Reject</p></td><td><p>Blocked (HTTP 403 error; raw values appear in error.data string)</p></td><td><p>No log emitted on reject</p></td></tr><tr><td><p>Log and mask</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Masked</p></td></tr><tr><td><p>Log</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Raw</p></td></tr></tbody></table>

### PII Detected in Response

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Response Body on Wire</th><th>Access Log</th></tr></thead><tbody><tr><td><p>Any (Reject, Log, Log and mask)</p></td><td><p>Pass-through (raw values flow to the client)</p></td><td><p>Raw</p></td></tr></tbody></table>

> [!IMPORTANT] For the A2A PII Detector policy, the **Log and mask** action only masks the access
> log, not the request body. Raw PII still flows to the upstream agent when using **Log** or **Log
> and mask** actions. Only **Reject** prevents PII from reaching the agent on the request side.

> [!IMPORTANT] Response-side detections are always logged with raw PII values and responses always
> pass through unchanged, regardless of the configured action. The policy never rejects or rewrites
> responses.

## See Also

- [MCP PII Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-pii-detector)

- [LLM PII Detection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-llm-pii-detection)

<!-- document id=4aa164a7b809a05502dfaa798387c0d667c668abe6dc082043e2f03201f53f88 url=/mulesoft/current/en-us/gateway/1.12/policies-included-a2a-prompt-decorator.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Prompt Decorator Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Prompt Decorator</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Prompt Decorator policy injects additional content into provided prompts before they are
sent to the upstream server. You can specify the content to inject either as a DataWeave string
parameter or by referencing a file. Additionally, you can use a DataWeave expression to filter which
requests should have prompts decorated.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The A2A Prompt Decorator policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Text Decorators</p></div></div></td><td><div><div><p>List of text decorations you want to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Prompt Text</p></div></div></td><td><div><div><p>DataWeave Expression that generates the prompt text injected into the request. For example: <code>#['Use Imperial metric units']</code>.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Decorators</p></div></div></td><td><div><div><p>List of file decorations to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Name</p></div></div></td><td><div><div><p>DataWeave Expression with the File Name. For example: <code>#['Decorator name']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Mime Type</p></div></div></td><td><div><div><p>DataWeave Expression with the Mime Type of the file to inject. For example: <code>#['application/json']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Source</p></div></div></td><td><div><div><p>Select <strong>Base64</strong> if the file Content is base64-encoded data, or <strong>Uri</strong> if the file Content is a URL to an external file.</p></div></div></td></tr><tr><td><div><div><p>Content</p></div></div></td><td><div><div><p>DataWeave Expression containing either base64-encoded file content or a URL to download the content file. For example: #['https://domain/file-location'] or #['QmFzZTY0IGVuY29kZWQgZmlsZSBjb250ZW50'].</p></div></div></td></tr></tbody></table>

<!-- document id=e8db298b1ba4a4fe3a581664fe0ce0c1f4223fc98fa67e296cd548bd1bea03d9 url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-prompt-decorator.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Prompt Decorator Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Prompt Decorator</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-prompt-decorator-release-notes">A2A Prompt Decorator</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Prompt Decorator policy injects additional content into provided prompts before they are
sent to the upstream server. You can specify the content to inject either as a DataWeave string
parameter or by referencing a file. Additionally, you can use a DataWeave expression to filter which
requests should have prompts decorated.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Prompt Decorator policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Text Decorators</p></div></div></td><td><div><div><p>List of text decorations you want to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Prompt Text</p></div></div></td><td><div><div><p>DataWeave Expression that generates the prompt text injected into the request. For example: <code>#['Use Imperial metric units']</code>.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Decorators</p></div></div></td><td><div><div><p>List of file decorations to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Name</p></div></div></td><td><div><div><p>DataWeave Expression with the File Name. For example: <code>#['Decorator name']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Mime Type</p></div></div></td><td><div><div><p>DataWeave Expression with the Mime Type of the file to inject. For example: <code>#['application/json']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Source</p></div></div></td><td><div><div><p>Select <strong>Base64</strong> if the file Content is base64-encoded data, or <strong>Uri</strong> if the file Content is a URL to an external file.</p></div></div></td></tr><tr><td><div><div><p>Content</p></div></div></td><td><div><div><p>DataWeave Expression containing either base64-encoded file content or a URL to download the content file. For example: #['https://domain/file-location'] or #['QmFzZTY0IGVuY29kZWQgZmlsZSBjb250ZW50'].</p></div></div></td></tr></tbody></table>

<!-- document id=545003b3b62de6ededb9d9bd9377526c23fc35e87e5ba66c4f4f0dad92e48752 url=/mulesoft/current/en-us/gateway/1.9/policies-included-a2a-prompt-decorator.md -->

---
product: Omni Gateway
version: 1.9
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Prompt Decorator Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Prompt Decorator</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Prompt Decorator policy injects additional content into provided prompts before they are
sent to the upstream server. You can specify the content to inject either as a DataWeave string
parameter or by referencing a file. Additionally, you can use a DataWeave expression to filter which
requests should have prompts decorated.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The A2A Prompt Decorator policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Text Decorators</p></div></div></td><td><div><div><p>List of text decorations you want to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Prompt Text</p></div></div></td><td><div><div><p>DataWeave Expression that generates the prompt text injected into the request. For example: <code>#['Use Imperial metric units']</code>.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Decorators</p></div></div></td><td><div><div><p>List of file decorations to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Name</p></div></div></td><td><div><div><p>DataWeave Expression with the File Name. For example: <code>#['Decorator name']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Mime Type</p></div></div></td><td><div><div><p>DataWeave Expression with the Mime Type of the file to inject. For example: <code>#['application/json']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Source</p></div></div></td><td><div><div><p>Select <strong>Base64</strong> if the file Content is base64-encoded data, or <strong>Uri</strong> if the file Content is a URL to an external file.</p></div></div></td></tr><tr><td><div><div><p>Content</p></div></div></td><td><div><div><p>DataWeave Expression containing either base64-encoded file content or a URL to download the content file. For example: #['https://domain/file-location'] or #['QmFzZTY0IGVuY29kZWQgZmlsZSBjb250ZW50'].</p></div></div></td></tr></tbody></table>

<!-- document id=0138842f93908e04e119d583b1d86d2bdcc9799766df58c637c068a896ec7e4a url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-prompt-decorator.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Prompt Decorator Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Prompt Decorator</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-prompt-decorator-release-notes">A2A Prompt Decorator</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Prompt Decorator policy injects additional content into provided prompts before they are
sent to the upstream server. You can specify the content to inject either as a DataWeave string
parameter or by referencing a file. Additionally, you can use a DataWeave expression to filter which
requests should have prompts decorated.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Prompt Decorator policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Text Decorators</p></div></div></td><td><div><div><p>List of text decorations you want to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Prompt Text</p></div></div></td><td><div><div><p>DataWeave Expression that generates the prompt text injected into the request. For example: <code>#['Use Imperial metric units']</code>.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Decorators</p></div></div></td><td><div><div><p>List of file decorations to add to the prompts.</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>DataWeave Expression that filters which prompts to decorate. For example: <code>#[attributes.headers['id']==1]</code>.</p></div></div></td></tr><tr><td><div><div><p>File Name</p></div></div></td><td><div><div><p>DataWeave Expression with the File Name. For example: <code>#['Decorator name']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Mime Type</p></div></div></td><td><div><div><p>DataWeave Expression with the Mime Type of the file to inject. For example: <code>#['application/json']</code>.</p></div></div></td></tr><tr><td><div><div><p>File Source</p></div></div></td><td><div><div><p>Select <strong>Base64</strong> if the file Content is base64-encoded data, or <strong>Uri</strong> if the file Content is a URL to an external file.</p></div></div></td></tr><tr><td><div><div><p>Content</p></div></div></td><td><div><div><p>DataWeave Expression containing either base64-encoded file content or a URL to download the content file. For example: #['https://domain/file-location'] or #['QmFzZTY0IGVuY29kZWQgZmlsZSBjb250ZW50'].</p></div></div></td></tr></tbody></table>

<!-- document id=1b10b5b7eb5b5e4b106978ad8d92f25ff4d06cb6ead187b08aa33dd1933bd5c6 url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-quality-evaluation.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Quality Evaluation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Quality Evaluation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates A2A agent task responses with an LLM to score quality and completeness</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-quality-evaluation-release-notes">A2A Quality Evaluation Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Quality Evaluation policy evaluates completed A2A agent task responses using an LLM to score
completeness against the original user intent. The policy only adds its verdict as response headers
and emits metrics for observability. The policy doesn’t block or modify the agent’s response.

The policy evaluates quality when the final agent response is available:

- **Synchronous responses** - When `message/send` returns a `200` status with the final response,
  the quality LLM is invoked inline before the response is returned.

- **Asynchronous responses** - When `message/send` returns a `202` status with a task ID, the policy
  stores the task metadata. Later, when `tasks/get` returns a `completed` state, the policy invokes
  the quality LLM and caches the verdict for subsequent polls.

> [!NOTE] This policy supports A2A `message/send` and `tasks/get` requests across all transport
> protocols.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Quality Evaluation policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Quality LLM URL</p></div></div></td><td><div><div><p>OpenAI-compatible chat completions endpoint for quality evaluation. The policy POSTs request to <code>&lt;qualityLlmUrl&gt;/v1/chat/completions</code>.</p></div><div><p>For example: <code><a href="https://api.openai.com">https://api.openai.com</a></code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Quality LLM API Key</p></div></div></td><td><div><div><p>Bearer token for authenticating to the quality LLM endpoint. This value is encrypted at rest.</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Quality LLM Model</p></div></div></td><td><div><div><p>Model name to use for quality evaluation. The name must be a valid model name supported by the configured endpoint.</p></div><div><p>For example: <code>gpt-4o</code> or <code>gpt-4o-mini</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>gpt-4o</code></p></div></div></td></tr><tr><td><div><div><p>Request Timeout (ms)</p></div></div></td><td><div><div><p>Timeout in milliseconds for the quality LLM call. If the call exceeds this timeout, the verdict isn’t attached and the policy logs a warning.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A Quality Evaluation policy intercepts A2A requests and evaluates completed agent responses
using a separate LLM. The policy works differently for synchronous and asynchronous agent responses.

### Request Filtering

The policy only processes requests that meet all of the following criteria:

- HTTP method is `POST`

- `Content-Type` header matches a JSON MIME type

- Request body parses as a valid JSON-RPC request

- JSON-RPC `method` is either `message/send` or `tasks/get`

All other requests pass through without evaluation.

### Synchronous Quality Flow (`message/send` with `200`)

When an agent returns a synchronous `200` response to `message/send`:

1.  The policy captures the original user message and the agent’s final response.

2.  The policy invokes the quality LLM with a prompt containing both the user message and agent
    response.

3.  The quality LLM returns a verdict with three fields:

    - `evaluation`: `"yes"` or `"no"` (whether the agent fully addressed the user’s request)

    - `value`: `"1"`, `"2"`, or `"3"` (quality score: 1=poor, 2=adequate, 3=excellent)

    - `explanation`: Free-text explanation of the verdict

4.  The policy adds quality verdict headers to the response.

    For header details, see [Quality Verdict Headers](#quality-verdict-headers).

5.  The policy emits a `mulesoft_agent_calls` counter metric with the verdict tags (see
    [Observability Metrics](#observability-metrics)).

6.  The response is returned to the client with the original agent response body and added quality
    headers.

The quality LLM call happens inline, so it adds latency (up to the configured timeout) to the
synchronous response path.

### Asynchronous Quality Flow (`message/send` with `202`, then `tasks/get`)

When an agent returns an asynchronous `202` response to `message/send`:

1.  The policy captures the original user message and the returned task ID.

2.  The policy stores the task metadata.

3.  The response is returned immediately to the client with no quality headers and no LLM call.

Later, when a client polls with `tasks/get` and the upstream returns `state: "completed"`:

1.  The policy invokes the quality LLM, stores the verdict, adds quality verdict headers, and emits
    the observability metric.

2.  The response is returned with the quality headers.

Subsequent polls of the same completed task return the stored verdict without re-invoking the LLM.

### Quality Verdict Headers

When a quality verdict is available, the policy adds these headers to the response:

<table><colgroup><col> <col></colgroup><thead><tr><th>Header</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-quality-evaluation</code></p></div></div></td><td><div><div><p><code>"yes"</code> or <code>"no"</code> indicating whether the agent fully addressed the user’s request.</p></div></div></td></tr><tr><td><div><div><p><code>x-quality-score</code></p></div></div></td><td><div><div><p>Quality score: <code>"1"</code> (poor), <code>"2"</code> (adequate), or <code>"3"</code> (excellent).</p></div></div></td></tr><tr><td><div><div><p><code>x-quality-explanation</code></p></div></div></td><td><div><div><p>Free-text explanation of the verdict provided by the quality LLM.</p></div></div></td></tr></tbody></table>

### Observability Metrics

Every time the quality LLM is invoked (synchronous `200` responses and the first `tasks/get` request
that evaluates a completed task), the policy emits a single increment of the `mulesoft_agent_calls`
counter metric.

The metric includes these tags:

<table><colgroup><col> <col></colgroup><thead><tr><th>Tag</th><th>Values</th></tr></thead><tbody><tr><td><div><div><p><code>mulesoft.a2a.task_resolution</code></p></div></div></td><td><div><div><p><code>"yes"</code>, <code>"no"</code> (verdict from the quality LLM), or <code>"unknown"</code> if the LLM call failed or the response couldn’t be parsed.</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.quality_score</code></p></div></div></td><td><div><div><p><code>"1"</code>, <code>"2"</code>, or <code>"3"</code> (score from the quality LLM), or <code>"unknown"</code> if the LLM call failed.</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.method</code></p></div></div></td><td><div><div><p><code>"message/send"</code> or <code>"tasks/get"</code> (the A2A method that triggered the evaluation).</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.latency_bucket</code></p></div></div></td><td><div><div><p>One of 20 bounded log-scale labels representing the quality LLM call latency in milliseconds: <code>"le_10"</code>, <code>"le_15"</code>, <code>"le_25"</code>, <code>"le_40"</code>, <code>"le_60"</code>, <code>"le_90"</code>, <code>"le_130"</code>, <code>"le_200"</code>, <code>"le_300"</code>, <code>"le_450"</code>, <code>"le_700"</code>, <code>"le_1000"</code>, <code>"le_1500"</code>, <code>"le_2200"</code>, <code>"le_3300"</code>, <code>"le_5000"</code>, <code>"le_7500"</code>, <code>"le_11000"</code>, <code>"le_16000"</code>, or <code>"gt_16000"</code>. Only emitted on successful LLM calls.</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.failure_reason</code></p></div></div></td><td><div><div><p>Only emitted when <code>task_resolution="unknown"</code>. Possible values: <code>"transport_error"</code>, <code>"http_&lt;code&gt;"</code>, <code>"parse_error"</code>, <code>"no_choices"</code>, or <code>"invalid_evaluation"</code>.</p></div></div></td></tr></tbody></table>

> [!IMPORTANT] The metric counts distinct quality LLM calls, not distinct tasks. A task answered
> synchronously via `200` produces one metric increment. A task accepted as `202` and later polled
> to `completed` also produces one metric increment (on the first `tasks/get` poll that evaluates
> the completed task). Subsequent polls against an already-evaluated task don’t emit additional
> metrics.

A sustained non-zero rate of `task_resolution="unknown"` indicates that the quality LLM is
unreachable or returning errors. Operators should alert on this condition.

## Failure Modes

The policy is designed to fail open — quality evaluation failures do not block agent responses.
Instead, failures are logged and reflected in observability metrics.

<table><colgroup><col> <col></colgroup><thead><tr><th>Failure</th><th>Impact</th></tr></thead><tbody><tr><td><div><div><p>Quality LLM unreachable, non-200 response, or parse error</p></div></div></td><td><div><div><p>No quality verdict headers are attached. The metric is emitted with <code>task_resolution="unknown"</code>, <code>quality_score="unknown"</code>, and an appropriate <code>failure_reason</code> tag. A warning is logged.</p></div></div></td></tr><tr><td><div><div><p>Verdict storage fails</p></div></div></td><td><div><div><p>The storage error is ignored. The policy may re-invoke the quality LLM on a subsequent <code>tasks/get</code> request. Both LLM calls are counted in the metric.</p></div></div></td></tr><tr><td><div><div><p>Request body is not valid JSON-RPC</p></div></div></td><td><div><div><p>The request passes through unchanged. No quality evaluation is performed.</p></div></div></td></tr><tr><td><div><div><p>Quality LLM call exceeds the configured timeout</p></div></div></td><td><div><div><p>Treated as a transport error. No quality verdict headers are attached. The metric is emitted with <code>task_resolution="unknown"</code> and <code>failure_reason="transport_error"</code>.</p></div></div></td></tr></tbody></table>

## Constraints and Limitations

- **Synchronous latency** - For synchronous `200` responses, the quality LLM call happens inline and
  can add up to the configured timeout in latency.

- **Asynchronous poll latency** - For asynchronous tasks, the first `tasks/get` poll that returns a
  `completed` state incurs the quality LLM call latency.

## Configuration Examples

The following examples demonstrate common configurations for the A2A Quality Evaluation policy using
different LLM models, timeouts, and endpoint configurations.

### Basic Configuration

This example configures the policy to evaluate agent responses using the `gpt-4o` model with a
10-second timeout:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-quality-evaluation
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-quality-evaluation-flex
  config:
    qualityLlmUrl: "https://api.openai.com"
    qualityLlmApiKey: "sk-proj-..."
    qualityLlmModel: "gpt-4o"
    timeout: 10000
```

### Custom Model and Timeout

This example uses a faster model (`gpt-4o-mini`) with a shorter timeout for lower latency:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-quality-evaluation-fast
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-quality-evaluation-flex
  config:
    qualityLlmUrl: "https://api.openai.com"
    qualityLlmApiKey: "sk-proj-..."
    qualityLlmModel: "gpt-4o-mini"
    timeout: 5000
```

### Using a Custom OpenAI-Compatible Endpoint

This example uses a self-hosted or alternative OpenAI-compatible endpoint:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-quality-evaluation-custom
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-quality-evaluation-flex
  config:
    qualityLlmUrl: "https://custom-llm.example.com"
    qualityLlmApiKey: "custom-api-key"
    qualityLlmModel: "custom-model-v1"
    timeout: 15000
```

## Sample Response Headers

The following examples demonstrate the quality evaluation headers and metrics added by the policy
for different response scenarios.

### Synchronous Quality Flow

When an agent returns a synchronous `200` response, the policy evaluates the response inline and
adds quality headers.

1.  The initial request is sent:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "parts": [
            {
              "kind": "text",
              "text": "Cancel my order #12345"
            }
          ]
        }
      }
    }
    ```

2.  The upstream agent returns `200` with the agent’s reply. The policy invokes the quality LLM,
    which returns:

    ```json
    {
      "evaluation": "yes",
      "value": "3",
      "explanation": "Order cancellation confirmed. The agent successfully canceled order #12345."
    }
    ```

3.  The policy adds these headers and emits these metrics:

    - Response headers:

      x-quality-evaluation: yes x-quality-score: 3 x-quality-explanation: Order cancellation
      confirmed. The agent successfully canceled order #12345.

    - Metric emitted:

      mulesoft\_agent\_calls{ task\_resolution="yes", quality\_score="3", method="message/send",
      latency\_bucket="le\_300" } 1

### Asynchronous Quality Flow

When an agent returns a `202` response, the policy stores the task metadata and defers evaluation
until the task is polled.

1.  Initial request is sent:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "parts": [
            {
              "kind": "text",
              "text": "Cancel my order #12345"
            }
          ]
        }
      }
    }
    ```

2.  The upstream agent returns `202`:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "id": "task-abc-123"
      }
    }
    ```

    The policy stores the task metadata. No quality headers are added. No metric is emitted.

3.  The client polls the task:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tasks/get",
      "params": {
        "id": "task-abc-123"
      }
    }
    ```

4.  The upstream agent returns `200` with completed status:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 2,
      "result": {
        "status": "completed",
        "message": {
          "parts": [
            {
              "kind": "text",
              "text": "Your order #12345 has been canceled."
            }
          ]
        }
      }
    }
    ```

5.  The policy invokes the quality LLM, stores the verdict, and adds these headers and emits these
    metrics:

    - Response headers:

      x-quality-evaluation: yes x-quality-score: 3 x-quality-explanation: Order cancellation
      confirmed.

    - Metric emitted:

      mulesoft\_agent\_calls{ task\_resolution="yes", quality\_score="3", method="tasks/get",
      latency\_bucket="le\_450" } 1

Subsequent polls of the same task return the stored verdict and do not invoke the LLM or emit
additional metrics.

## See Also

- [A2A Prompt Decorator Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-prompt-decorator)

- [A2A Personally Identifiable Information (PII) Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-pii-detector)

- [A2A Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-token-rate-limit)

<!-- document id=d128c7de1ef10c494e991a0ed84df724ffbc6f1ff0edd03d93acd0fe36bc1425 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-quality-evaluation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Quality Evaluation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Quality Evaluation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates A2A agent task responses with an LLM to score quality and completeness</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-quality-evaluation-release-notes">A2A Quality Evaluation Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Quality Evaluation policy evaluates completed A2A agent task responses using an LLM to score
completeness against the original user intent. The policy only adds its verdict as response headers
and emits metrics for observability. The policy doesn’t block or modify the agent’s response.

The policy evaluates quality when the final agent response is available:

- **Synchronous responses** - When `message/send` returns a `200` status with the final response,
  the quality LLM is invoked inline before the response is returned.

- **Asynchronous responses** - When `message/send` returns a `202` status with a task ID, the policy
  stores the task metadata. Later, when `tasks/get` returns a `completed` state, the policy invokes
  the quality LLM and caches the verdict for subsequent polls.

> [!NOTE] This policy supports A2A `message/send` and `tasks/get` requests across all transport
> protocols.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Quality Evaluation policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Quality LLM URL</p></div></div></td><td><div><div><p>OpenAI-compatible chat completions endpoint for quality evaluation. The policy POSTs request to <code>&lt;qualityLlmUrl&gt;/v1/chat/completions</code>.</p></div><div><p>For example: <code><a href="https://api.openai.com">https://api.openai.com</a></code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Quality LLM API Key</p></div></div></td><td><div><div><p>Bearer token for authenticating to the quality LLM endpoint. This value is encrypted at rest.</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Quality LLM Model</p></div></div></td><td><div><div><p>Model name to use for quality evaluation. The name must be a valid model name supported by the configured endpoint.</p></div><div><p>For example: <code>gpt-4o</code> or <code>gpt-4o-mini</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>gpt-4o</code></p></div></div></td></tr><tr><td><div><div><p>Request Timeout (ms)</p></div></div></td><td><div><div><p>Timeout in milliseconds for the quality LLM call. If the call exceeds this timeout, the verdict isn’t attached and the policy logs a warning.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A Quality Evaluation policy intercepts A2A requests and evaluates completed agent responses
using a separate LLM. The policy works differently for synchronous and asynchronous agent responses.

### Request Filtering

The policy only processes requests that meet all of the following criteria:

- HTTP method is `POST`

- `Content-Type` header matches a JSON MIME type

- Request body parses as a valid JSON-RPC request

- JSON-RPC `method` is either `message/send` or `tasks/get`

All other requests pass through without evaluation.

### Synchronous Quality Flow (`message/send` with `200`)

When an agent returns a synchronous `200` response to `message/send`:

1.  The policy captures the original user message and the agent’s final response.

2.  The policy invokes the quality LLM with a prompt containing both the user message and agent
    response.

3.  The quality LLM returns a verdict with three fields:

    - `evaluation`: `"yes"` or `"no"` (whether the agent fully addressed the user’s request)

    - `value`: `"1"`, `"2"`, or `"3"` (quality score: 1=poor, 2=adequate, 3=excellent)

    - `explanation`: Free-text explanation of the verdict

4.  The policy adds quality verdict headers to the response.

    For header details, see [Quality Verdict Headers](#quality-verdict-headers).

5.  The policy emits a `mulesoft_agent_calls` counter metric with the verdict tags (see
    [Observability Metrics](#observability-metrics)).

6.  The response is returned to the client with the original agent response body and added quality
    headers.

The quality LLM call happens inline, so it adds latency (up to the configured timeout) to the
synchronous response path.

### Asynchronous Quality Flow (`message/send` with `202`, then `tasks/get`)

When an agent returns an asynchronous `202` response to `message/send`:

1.  The policy captures the original user message and the returned task ID.

2.  The policy stores the task metadata.

3.  The response is returned immediately to the client with no quality headers and no LLM call.

Later, when a client polls with `tasks/get` and the upstream returns `state: "completed"`:

1.  The policy invokes the quality LLM, stores the verdict, adds quality verdict headers, and emits
    the observability metric.

2.  The response is returned with the quality headers.

Subsequent polls of the same completed task return the stored verdict without re-invoking the LLM.

### Quality Verdict Headers

When a quality verdict is available, the policy adds these headers to the response:

<table><colgroup><col> <col></colgroup><thead><tr><th>Header</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-quality-evaluation</code></p></div></div></td><td><div><div><p><code>"yes"</code> or <code>"no"</code> indicating whether the agent fully addressed the user’s request.</p></div></div></td></tr><tr><td><div><div><p><code>x-quality-score</code></p></div></div></td><td><div><div><p>Quality score: <code>"1"</code> (poor), <code>"2"</code> (adequate), or <code>"3"</code> (excellent).</p></div></div></td></tr><tr><td><div><div><p><code>x-quality-explanation</code></p></div></div></td><td><div><div><p>Free-text explanation of the verdict provided by the quality LLM.</p></div></div></td></tr></tbody></table>

### Observability Metrics

Every time the quality LLM is invoked (synchronous `200` responses and the first `tasks/get` request
that evaluates a completed task), the policy emits a single increment of the `mulesoft_agent_calls`
counter metric.

The metric includes these tags:

<table><colgroup><col> <col></colgroup><thead><tr><th>Tag</th><th>Values</th></tr></thead><tbody><tr><td><div><div><p><code>mulesoft.a2a.task_resolution</code></p></div></div></td><td><div><div><p><code>"yes"</code>, <code>"no"</code> (verdict from the quality LLM), or <code>"unknown"</code> if the LLM call failed or the response couldn’t be parsed.</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.quality_score</code></p></div></div></td><td><div><div><p><code>"1"</code>, <code>"2"</code>, or <code>"3"</code> (score from the quality LLM), or <code>"unknown"</code> if the LLM call failed.</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.method</code></p></div></div></td><td><div><div><p><code>"message/send"</code> or <code>"tasks/get"</code> (the A2A method that triggered the evaluation).</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.latency_bucket</code></p></div></div></td><td><div><div><p>One of 20 bounded log-scale labels representing the quality LLM call latency in milliseconds: <code>"le_10"</code>, <code>"le_15"</code>, <code>"le_25"</code>, <code>"le_40"</code>, <code>"le_60"</code>, <code>"le_90"</code>, <code>"le_130"</code>, <code>"le_200"</code>, <code>"le_300"</code>, <code>"le_450"</code>, <code>"le_700"</code>, <code>"le_1000"</code>, <code>"le_1500"</code>, <code>"le_2200"</code>, <code>"le_3300"</code>, <code>"le_5000"</code>, <code>"le_7500"</code>, <code>"le_11000"</code>, <code>"le_16000"</code>, or <code>"gt_16000"</code>. Only emitted on successful LLM calls.</p></div></div></td></tr><tr><td><div><div><p><code>mulesoft.a2a.failure_reason</code></p></div></div></td><td><div><div><p>Only emitted when <code>task_resolution="unknown"</code>. Possible values: <code>"transport_error"</code>, <code>"http_&lt;code&gt;"</code>, <code>"parse_error"</code>, <code>"no_choices"</code>, or <code>"invalid_evaluation"</code>.</p></div></div></td></tr></tbody></table>

> [!IMPORTANT] The metric counts distinct quality LLM calls, not distinct tasks. A task answered
> synchronously via `200` produces one metric increment. A task accepted as `202` and later polled
> to `completed` also produces one metric increment (on the first `tasks/get` poll that evaluates
> the completed task). Subsequent polls against an already-evaluated task don’t emit additional
> metrics.

A sustained non-zero rate of `task_resolution="unknown"` indicates that the quality LLM is
unreachable or returning errors. Operators should alert on this condition.

## Failure Modes

The policy is designed to fail open — quality evaluation failures do not block agent responses.
Instead, failures are logged and reflected in observability metrics.

<table><colgroup><col> <col></colgroup><thead><tr><th>Failure</th><th>Impact</th></tr></thead><tbody><tr><td><div><div><p>Quality LLM unreachable, non-200 response, or parse error</p></div></div></td><td><div><div><p>No quality verdict headers are attached. The metric is emitted with <code>task_resolution="unknown"</code>, <code>quality_score="unknown"</code>, and an appropriate <code>failure_reason</code> tag. A warning is logged.</p></div></div></td></tr><tr><td><div><div><p>Verdict storage fails</p></div></div></td><td><div><div><p>The storage error is ignored. The policy may re-invoke the quality LLM on a subsequent <code>tasks/get</code> request. Both LLM calls are counted in the metric.</p></div></div></td></tr><tr><td><div><div><p>Request body is not valid JSON-RPC</p></div></div></td><td><div><div><p>The request passes through unchanged. No quality evaluation is performed.</p></div></div></td></tr><tr><td><div><div><p>Quality LLM call exceeds the configured timeout</p></div></div></td><td><div><div><p>Treated as a transport error. No quality verdict headers are attached. The metric is emitted with <code>task_resolution="unknown"</code> and <code>failure_reason="transport_error"</code>.</p></div></div></td></tr></tbody></table>

## Constraints and Limitations

- **Synchronous latency** - For synchronous `200` responses, the quality LLM call happens inline and
  can add up to the configured timeout in latency.

- **Asynchronous poll latency** - For asynchronous tasks, the first `tasks/get` poll that returns a
  `completed` state incurs the quality LLM call latency.

## Configuration Examples

The following examples demonstrate common configurations for the A2A Quality Evaluation policy using
different LLM models, timeouts, and endpoint configurations.

### Basic Configuration

This example configures the policy to evaluate agent responses using the `gpt-4o` model with a
10-second timeout:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-quality-evaluation
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-quality-evaluation-flex
  config:
    qualityLlmUrl: "https://api.openai.com"
    qualityLlmApiKey: "sk-proj-..."
    qualityLlmModel: "gpt-4o"
    timeout: 10000
```

### Custom Model and Timeout

This example uses a faster model (`gpt-4o-mini`) with a shorter timeout for lower latency:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-quality-evaluation-fast
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-quality-evaluation-flex
  config:
    qualityLlmUrl: "https://api.openai.com"
    qualityLlmApiKey: "sk-proj-..."
    qualityLlmModel: "gpt-4o-mini"
    timeout: 5000
```

### Using a Custom OpenAI-Compatible Endpoint

This example uses a self-hosted or alternative OpenAI-compatible endpoint:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-quality-evaluation-custom
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-quality-evaluation-flex
  config:
    qualityLlmUrl: "https://custom-llm.example.com"
    qualityLlmApiKey: "custom-api-key"
    qualityLlmModel: "custom-model-v1"
    timeout: 15000
```

## Sample Response Headers

The following examples demonstrate the quality evaluation headers and metrics added by the policy
for different response scenarios.

### Synchronous Quality Flow

When an agent returns a synchronous `200` response, the policy evaluates the response inline and
adds quality headers.

1.  The initial request is sent:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "parts": [
            {
              "kind": "text",
              "text": "Cancel my order #12345"
            }
          ]
        }
      }
    }
    ```

2.  The upstream agent returns `200` with the agent’s reply. The policy invokes the quality LLM,
    which returns:

    ```json
    {
      "evaluation": "yes",
      "value": "3",
      "explanation": "Order cancellation confirmed. The agent successfully canceled order #12345."
    }
    ```

3.  The policy adds these headers and emits these metrics:

    - Response headers:

      x-quality-evaluation: yes x-quality-score: 3 x-quality-explanation: Order cancellation
      confirmed. The agent successfully canceled order #12345.

    - Metric emitted:

      mulesoft\_agent\_calls{ task\_resolution="yes", quality\_score="3", method="message/send",
      latency\_bucket="le\_300" } 1

### Asynchronous Quality Flow

When an agent returns a `202` response, the policy stores the task metadata and defers evaluation
until the task is polled.

1.  Initial request is sent:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "parts": [
            {
              "kind": "text",
              "text": "Cancel my order #12345"
            }
          ]
        }
      }
    }
    ```

2.  The upstream agent returns `202`:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "id": "task-abc-123"
      }
    }
    ```

    The policy stores the task metadata. No quality headers are added. No metric is emitted.

3.  The client polls the task:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tasks/get",
      "params": {
        "id": "task-abc-123"
      }
    }
    ```

4.  The upstream agent returns `200` with completed status:

    ```json
    {
      "jsonrpc": "2.0",
      "id": 2,
      "result": {
        "status": "completed",
        "message": {
          "parts": [
            {
              "kind": "text",
              "text": "Your order #12345 has been canceled."
            }
          ]
        }
      }
    }
    ```

5.  The policy invokes the quality LLM, stores the verdict, and adds these headers and emits these
    metrics:

    - Response headers:

      x-quality-evaluation: yes x-quality-score: 3 x-quality-explanation: Order cancellation
      confirmed.

    - Metric emitted:

      mulesoft\_agent\_calls{ task\_resolution="yes", quality\_score="3", method="tasks/get",
      latency\_bucket="le\_450" } 1

Subsequent polls of the same task return the stored verdict and do not invoke the LLM or emit
additional metrics.

## See Also

- [A2A Prompt Decorator Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-prompt-decorator)

- [A2A Personally Identifiable Information (PII) Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-pii-detector)

- [A2A Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-token-rate-limit)

<!-- document id=d634d039577b52b2f229279fa82c55015e5cdcac76c0aab0b17090cfeb327962 url=/mulesoft/current/en-us/gateway/1.12/policies-included-a2a-schema-validation.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates Agent requests to ensure they conform to the A2A specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Schema Validation policy validates that every request to the A2A server complies with the
A2A schema. If validation fails it will report a Policy Violation.

There are no configuration parameters for this policy.

### Flex Gateway Local Mode

The A2A Schema Validation policy isn’t supported in Local Mode.

<!-- document id=99c5c42539f9a06f9953e59a1b04146b33d57c300d18040d239bdf69d977b5b8 url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-schema-validation.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates Agent requests to ensure they conform to the A2A specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-schema-validation-release-notes">A2A Schema Validation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Schema Validation policy validates that every request to the A2A server complies with the
A2A schema. If validation fails it will report a Policy Violation.

There are no configuration parameters for this policy.

### Omni Gateway Local Mode

The A2A Schema Validation policy isn’t supported in Local Mode.

<!-- document id=eed492e2f4b879d31832ff0e6081c6c72289251df0865785062cf2a362cc736b url=/mulesoft/current/en-us/gateway/1.9/policies-included-a2a-schema-validation.md -->

---
product: Omni Gateway
version: 1.9
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates Agent requests to ensure they conform to the A2A specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Schema Validation policy validates that every request to the A2A server complies with the
A2A schema. If validation fails it will report a Policy Violation.

There are no configuration parameters for this policy.

### Flex Gateway Local Mode

The A2A Schema Validation policy isn’t supported in Local Mode.

<!-- document id=1deb026339add81614d90d902deed76e90cfe167df3a075c79530e67c1f2e0eb url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-schema-validation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates Agent requests to ensure they conform to the A2A specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-schema-validation-release-notes">A2A Schema Validation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Schema Validation policy validates that every request to the A2A server complies with the
A2A schema. If validation fails it will report a Policy Violation.

There are no configuration parameters for this policy.

### Omni Gateway Local Mode

The A2A Schema Validation policy isn’t supported in Local Mode.

<!-- document id=ac4078c38edf26b1f9e4885ff63d5e03fd4efafb8ae5010a53dd01bcd1a04834 url=/mulesoft/current/en-us/gateway/1.12/policies-included-a2a-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, rate limiting, token, a2a
---

# A2A Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits agent usage of upstream resources</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Token Based Rate Limit policy enforces rate limiting on agent requests based on the number
of tokens consumed by the agents. The A2A Token Based Rate Limit policy counts tokens using the
GPT-4o-mini tokenizer model, providing control over API usage based on the content being processed.

The policy counts tokens from both request and response payloads. Tokens generated by the response
are counted toward the rate limit of the next request to ensure total token consumption across the
conversation is properly tracked.

If a request exceeds the allowed token limit, the policy blocks the call and returns a `429` status
code.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The A2A Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed within the specified time period. Must be a positive integer of one or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit window. Minimum time period is 1000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. For example:</p></div><div><ul><li><p><code>#[attributes.headers['ClientId']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per user</p></li><li><p><code>#[attributes.headers['X-Forwarded-For']]</code>: Rate limit per IP address</p></li><li><p><code>#[attributes.requestPath]</code>: Rate limit per API path</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A Token Based Rate Limit policy monitors token consumption in the current window, allowing
requests to reach the backend only if the available token quota is greater than zero.

The policy uses a fixed-window rate limiting algorithm. The window starts after it receives the
first request. When the quota is exhausted, requests are rejected with a 429 status code until the
time window resets.

The `keySelector` parameter enables you to create independent rate limit counters for different
groups of requests. Each unique value resolved by the DataWeave expression has its own token quota
and time window. For example, if you configure `keySelector: "#[attributes.headers['ClientId']]"`
with a limit of 100 tokens per 5 seconds, each individual client has its own 100-token quota in a
5-second window. If you don’t configure a key selector, all requests are counted together.

### Token Counting

The policy uses the GPT-4o-mini tokenizer model to count tokens in:

- **Request payloads**: Tokens are counted from the `params.message.parts` array in JSON-RPC
  requests. The policy extracts text from parts with `kind: "text"` or `type: "text"`, and data from
  parts with `kind: "data"` or `type: "data"`.

- **Response payloads**: Tokens are counted from response content including:

  - Direct message parts in `result.parts`

  - Status message parts in `result.status.message.parts`

  - Artifact parts in `result.artifacts[*].parts`

  - Server-Sent Events (SSE) stream data

To learn more about the GPT-4o-mini tokenizer model, see
[OpenAI Platform Tokenizer](https://platform.openai.com/tokenizer).

### Response Headers

When a request is processed, the policy adds the following headers to the response:

- `x-token-limit`: The maximum number of tokens allowed per window

- `x-token-remaining`: The number of tokens remaining in the current window

- `x-token-reset`: The remaining time, in milliseconds, until a new window starts

<!-- document id=12c9573857751556a2cbef071c8d5589c85b6ce7810de6e911eefae9495ce7ae url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, rate limiting, token, a2a
---

# A2A Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits agent usage of upstream resources</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-token-rate-limit-release-notes">A2A Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Token Based Rate Limit policy enforces rate limiting on agent requests based on the number
of tokens consumed by the agents. The A2A Token Based Rate Limit policy counts tokens using the
GPT-4o-mini tokenizer model, providing control over API usage based on the content being processed.

The policy counts tokens from both request and response payloads. Tokens generated by the response
are counted toward the rate limit of the next request to ensure total token consumption across the
conversation is properly tracked.

If a request exceeds the allowed token limit, the policy blocks the call and returns a `429` status
code.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed within the specified time period. Must be a positive integer of one or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit window. Minimum time period is 1000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. For example:</p></div><div><ul><li><p><code>#[attributes.headers['ClientId']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per user</p></li><li><p><code>#[attributes.headers['X-Forwarded-For']]</code>: Rate limit per IP address</p></li><li><p><code>#[attributes.requestPath]</code>: Rate limit per API path</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A Token Based Rate Limit policy monitors token consumption in the current window, allowing
requests to reach the backend only if the available token quota is greater than zero.

The policy uses a fixed-window rate limiting algorithm. The window starts after it receives the
first request. When the quota is exhausted, requests are rejected with a 429 status code until the
time window resets.

The `keySelector` parameter enables you to create independent rate limit counters for different
groups of requests. Each unique value resolved by the DataWeave expression has its own token quota
and time window. For example, if you configure `keySelector: "#[attributes.headers['ClientId']]"`
with a limit of 100 tokens per 5 seconds, each individual client has its own 100-token quota in a
5-second window. If you don’t configure a key selector, all requests are counted together.

### Token Counting

The policy uses the GPT-4o-mini tokenizer model to count tokens in:

- **Request payloads**: Tokens are counted from the `params.message.parts` array in JSON-RPC
  requests. The policy extracts text from parts with `kind: "text"` or `type: "text"`, and data from
  parts with `kind: "data"` or `type: "data"`.

- **Response payloads**: Tokens are counted from response content including:

  - Direct message parts in `result.parts`

  - Status message parts in `result.status.message.parts`

  - Artifact parts in `result.artifacts[*].parts`

  - Server-Sent Events (SSE) stream data

To learn more about the GPT-4o-mini tokenizer model, see
[OpenAI Platform Tokenizer](https://platform.openai.com/tokenizer).

### Response Headers

When a request is processed, the policy adds the following headers to the response:

- `x-token-limit`: The maximum number of tokens allowed per window

- `x-token-remaining`: The number of tokens remaining in the current window

- `x-token-reset`: The remaining time, in milliseconds, until a new window starts

<!-- document id=b9b2e9b886a7c12b70c41e2f6b72d67bea8f777d804405b7af364e7bb26be700 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, rate limiting, token, a2a
---

# A2A Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits agent usage of upstream resources</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-token-rate-limit-release-notes">A2A Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A Token Based Rate Limit policy enforces rate limiting on agent requests based on the number
of tokens consumed by the agents. The A2A Token Based Rate Limit policy counts tokens using the
GPT-4o-mini tokenizer model, providing control over API usage based on the content being processed.

The policy counts tokens from both request and response payloads. Tokens generated by the response
are counted toward the rate limit of the next request to ensure total token consumption across the
conversation is properly tracked.

If a request exceeds the allowed token limit, the policy blocks the call and returns a `429` status
code.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed within the specified time period. Must be a positive integer of one or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit window. Minimum time period is 1000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. For example:</p></div><div><ul><li><p><code>#[attributes.headers['ClientId']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per user</p></li><li><p><code>#[attributes.headers['X-Forwarded-For']]</code>: Rate limit per IP address</p></li><li><p><code>#[attributes.requestPath]</code>: Rate limit per API path</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A Token Based Rate Limit policy monitors token consumption in the current window, allowing
requests to reach the backend only if the available token quota is greater than zero.

The policy uses a fixed-window rate limiting algorithm. The window starts after it receives the
first request. When the quota is exhausted, requests are rejected with a 429 status code until the
time window resets.

The `keySelector` parameter enables you to create independent rate limit counters for different
groups of requests. Each unique value resolved by the DataWeave expression has its own token quota
and time window. For example, if you configure `keySelector: "#[attributes.headers['ClientId']]"`
with a limit of 100 tokens per 5 seconds, each individual client has its own 100-token quota in a
5-second window. If you don’t configure a key selector, all requests are counted together.

### Token Counting

The policy uses the GPT-4o-mini tokenizer model to count tokens in:

- **Request payloads**: Tokens are counted from the `params.message.parts` array in JSON-RPC
  requests. The policy extracts text from parts with `kind: "text"` or `type: "text"`, and data from
  parts with `kind: "data"` or `type: "data"`.

- **Response payloads**: Tokens are counted from response content including:

  - Direct message parts in `result.parts`

  - Status message parts in `result.status.message.parts`

  - Artifact parts in `result.artifacts[*].parts`

  - Server-Sent Events (SSE) stream data

To learn more about the GPT-4o-mini tokenizer model, see
[OpenAI Platform Tokenizer](https://platform.openai.com/tokenizer).

### Response Headers

When a request is processed, the policy adds the following headers to the response:

- `x-token-limit`: The maximum number of tokens allowed per window

- `x-token-remaining`: The number of tokens remaining in the current window

- `x-token-reset`: The remaining time, in milliseconds, until a new window starts

<!-- document id=697e5c42ad80609691259fc348d49989170c2be086163648f5215b02e52b2270 url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-agent-card.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Agent Card Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Agent Card</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-agent-card-release-notes">A2A v1 Agent Card Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Agent-to-Agent (A2A) v1 Agent Card Policy rewrites the interface URLs inside an A2A v1.0 agent
card so that clients reach the agent through Omni Gateway rather than connecting directly to backend
services. This ensures that all client requests are routed through Omni Gateway, enabling it to
enforce security and access controls.

The policy rewrites the `url` field for every supported interface (`JSONRPC`, `GRPC`, `HTTP+JSON`)
in the `supportedInterfaces[]` array of the agent card response. Custom protocol bindings aren’t
edited.

The policy handles the following response formats:

- Bare card response (`GET /.well-known/agent-card.json` or `GET /extendedAgentCard`)

- JSON-RPC envelope responses (`GetExtendedAgentCard`)

- Server-Sent Events (SSE) streams (`SendStreamingMessage`, `SubscribeToTask`)

The A2A v1 Agent Card policy also enables the **Total Agent Calls** metric that tracks the total
successful and unsuccessful calls made to the agent. To view **Total Agent Calls**, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-view-api-metrics).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Agent Card policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required</th><th>Default Value</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Consumer URL</p></div></div></td><td><div><div><p>The base gateway URL injected into the agent card’s <code>supportedInterfaces[]</code> entries. Each binding’s final URL is the Consumer URL joined with its Interface Paths value (or the bare Consumer URL when no path is set).</p></div><div><p>When undefined, the gateway resolves its public consumer URL from the Anypoint platform.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Resolved from platform</p></div></div></td><td><div><div><p><code>https://gateway.public.example.com/agent/</code></p></div></div></td></tr><tr><td><div><div><p>Agent Card Path</p></div></div></td><td><div><div><p>The suffix path where the well-known agent card is published. The match is case-insensitive and suffix-based, so the configured path resolves under any tenant prefix.</p></div><div><p>Configure this when the gateway publishes the card under a custom sub-path.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>/.well-known/agent-card.json</code></p></div></div></td><td><div><div><p><code>/agents/finance/.well-known/agent-card.json</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - JSON-RPC Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>JSONRPC</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/jsonrpc</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - gRPC Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>GRPC</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/grpc</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - HTTP+JSON Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>HTTP+JSON</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/rest</code></p></div></div></td></tr></tbody></table>

## Examples

### Basic Configuration

This example applies the policy with default settings (agent card at `/.well-known/agent-card.json`,
consumer URL resolved from platform).

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
```

### Override Consumer URL

This example overrides the consumer URL when running behind a CDN or reverse proxy that the Anypoint
platform doesn’t see.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
  config:
    consumerUrl: "https://gateway.public.example.com/agent/"
```

### Custom Card Path

This example matches a custom card path when your agent is mounted under a tenant prefix.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
  config:
    cardPath: "/agents/finance/.well-known/agent-card.json"
```

### Per-Transport Paths

This example gives each transport its own sub-path under the gateway. The final URL for each binding
is the Consumer URL joined with its path.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
  config:
    consumerUrl: "https://gateway.public.example.com/agent/"
    interfacePaths:
      jsonRpc: "/jsonrpc"
      grpc: "/grpc"
      httpJson: "/rest"
```

<!-- document id=dcd7271d192c98077e66c5694e037253aa0e22d025d8630ee93622c986522240 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-agent-card.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Agent Card Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Agent Card</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-agent-card-release-notes">A2A v1 Agent Card Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Agent-to-Agent (A2A) v1 Agent Card Policy rewrites the interface URLs inside an A2A v1.0 agent
card so that clients reach the agent through Omni Gateway rather than connecting directly to backend
services. This ensures that all client requests are routed through Omni Gateway, enabling it to
enforce security and access controls.

The policy rewrites the `url` field for every supported interface (`JSONRPC`, `GRPC`, `HTTP+JSON`)
in the `supportedInterfaces[]` array of the agent card response. Custom protocol bindings aren’t
edited.

The policy handles the following response formats:

- Bare card response (`GET /.well-known/agent-card.json` or `GET /extendedAgentCard`)

- JSON-RPC envelope responses (`GetExtendedAgentCard`)

- Server-Sent Events (SSE) streams (`SendStreamingMessage`, `SubscribeToTask`)

The A2A v1 Agent Card policy also enables the **Total Agent Calls** metric that tracks the total
successful and unsuccessful calls made to the agent. To view **Total Agent Calls**, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-view-api-metrics).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Agent Card policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required</th><th>Default Value</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Consumer URL</p></div></div></td><td><div><div><p>The base gateway URL injected into the agent card’s <code>supportedInterfaces[]</code> entries. Each binding’s final URL is the Consumer URL joined with its Interface Paths value (or the bare Consumer URL when no path is set).</p></div><div><p>When undefined, the gateway resolves its public consumer URL from the Anypoint platform.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Resolved from platform</p></div></div></td><td><div><div><p><code>https://gateway.public.example.com/agent/</code></p></div></div></td></tr><tr><td><div><div><p>Agent Card Path</p></div></div></td><td><div><div><p>The suffix path where the well-known agent card is published. The match is case-insensitive and suffix-based, so the configured path resolves under any tenant prefix.</p></div><div><p>Configure this when the gateway publishes the card under a custom sub-path.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>/.well-known/agent-card.json</code></p></div></div></td><td><div><div><p><code>/agents/finance/.well-known/agent-card.json</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - JSON-RPC Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>JSONRPC</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/jsonrpc</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - gRPC Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>GRPC</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/grpc</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - HTTP+JSON Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>HTTP+JSON</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/rest</code></p></div></div></td></tr></tbody></table>

## Examples

### Basic Configuration

This example applies the policy with default settings (agent card at `/.well-known/agent-card.json`,
consumer URL resolved from platform).

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
```

### Override Consumer URL

This example overrides the consumer URL when running behind a CDN or reverse proxy that the Anypoint
platform doesn’t see.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
  config:
    consumerUrl: "https://gateway.public.example.com/agent/"
```

### Custom Card Path

This example matches a custom card path when your agent is mounted under a tenant prefix.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
  config:
    cardPath: "/agents/finance/.well-known/agent-card.json"
```

### Per-Transport Paths

This example gives each transport its own sub-path under the gateway. The final URL for each binding
is the Consumer URL joined with its path.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-agent-card
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-agent
  policyRef:
    name: a-two-a-v1-agent-card-flex
    namespace: default
  config:
    consumerUrl: "https://gateway.public.example.com/agent/"
    interfacePaths:
      jsonRpc: "/jsonrpc"
      grpc: "/grpc"
      httpJson: "/rest"
```

<!-- document id=1bd190b94642a906267a7cdb5184e890bbfcc66b25326473e279d48972fdebe1 url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-azure-guardrails.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, a2a, azure, content safety, guardrails, harm detection, jailbreak, hallucination
---

# A2A v1 Azure Content Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Azure Content Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates A2A v1 agent messages against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-azure-guardrails-release-notes">A2A v1 Azure Content Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates Azure Content Safety policies</p></td></tr><tr><td><p>503 - Service Unavailable: Azure API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The A2A v1 Azure Content Guardrails policy provides comprehensive content moderation for A2A v1.0
agent traffic by evaluating requests and responses against the Azure AI Content Safety service. The
policy integrates with
[Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)
to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across four categories (**Hate**,
  **SelfHarm**, **Sexual**, and **Violence**) with configurable severity thresholds (`0`, `2`, `4`,
  `6`).

- **Prompt Shield**: Detects jailbreak attempts and indirect prompt-injection attacks using Azure’s
  advanced detection capabilities.

- **Blocklists**: Blocks content matching Azure-managed custom blocklists you define in Azure
  Content Safety Studio.

- **Groundedness Detection**: Evaluates whether agent responses are grounded in provided reference
  text (hallucination detection for RAG applications).

- **Protected Material Detection**: Detects known copyrighted text in agent responses.

The policy operates across three A2A v1.0 transport protocols:

- **JSON-RPC** — Moderates `SendMessage` and `SendStreamingMessage` on both request and response

- **HTTP+JSON** — Moderates `POST /message:send` and streaming responses

- **gRPC** — Pass-through without moderation in v1.0

The policy operates in independent phases:

- **Request phase**: Moderates user messages before they reach the upstream agent, preventing
  harmful or inappropriate messages from being processed.

- **Response phase**: Moderates agent responses before they reach the client, ensuring outputs
  comply with safety policies.

- **Streaming response phase**: Best-effort moderation of streaming responses by buffering frame
  bodies and scanning on configurable thresholds.

When content violates safety policies, the request is rejected with a `403` error code and never
reaches the agent (request phase) or the client receives a `403` instead of the agent response
(response phase).

> [!NOTE] This policy is designed for A2A v1.0 traffic only. gRPC traffic passes through without
> moderation in this version.

## Before You Begin

Before configuring this policy, you need:

1.  **Azure Account** with access to Azure AI Content Safety

2.  **Azure Content Safety Resource** created in the Azure Portal

3.  **Subscription Key** from the Azure Portal (Keys and Endpoint section)

4.  **Resource Endpoint URL** from the Azure Portal configured as a Flex service

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Azure Content Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Azure Content Safety Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety endpoint base URL configured as a Flex service, for example, <code>https://&lt;resource&gt;.cognitiveservices.azure.com</code>. The policy appends endpoint paths at runtime.</p></div></div></td></tr><tr><td><div><div><p>Azure API Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety subscription key. The key is passed in the <code>Ocp-Apim-Subscription-Key</code> header and marked as sensitive.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the user message against Azure Content Safety before forwarding to the upstream agent. Rejected messages never reach the agent. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the agent response against Azure Content Safety before returning to the client. Rejected responses return <code>403</code> error code. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Moderate Streaming Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates streaming responses by buffering frame bodies and scanning on configurable thresholds. When disabled, streaming responses pass through unchanged. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Default Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Severity threshold applied to all four harm categories (Hate, SelfHarm, Sexual, Violence). Content with severity at or above this value is rejected. Supported values are <code>0</code>, <code>2</code> (default), <code>4</code>, and <code>6</code>.</p></div><div><p>For details, see <a href="#severity-thresholds">Severity Thresholds</a>.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>API Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Azure Content Safety API version used for all endpoint calls. Default: <code>2024-09-01</code>.</p></div><div><p>To enable Groundedness Detection, override this to a supported preview version, for example, <code>2024-09-15-preview</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Prompt Shield</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:shieldPrompt</code> alongside <code>text:analyze</code> on the request to detect jailbreak attempts and indirect prompt-injection attacks. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Hate Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Hate harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>SelfHarm Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the SelfHarm harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Sexual Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Sexual harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Violence Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Violence harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Blocklist Names</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Names of Azure-managed blocklists (created in Azure Content Safety Studio) to evaluate against the input text.</p></div></div></td></tr><tr><td><div><div><p>Enable Groundedness Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectGroundedness</code> on the agent response to detect hallucinated statements. Requires Moderate Response enabled and Grounding Source Selector to be set. Only available in Azure regions that support the API, and only on preview API versions (for example, <code>2024-09-15-preview</code>).</p></div></div></td></tr><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression resolving the grounding source text from the canonical A2A request body. Required when Groundedness Detection is enabled. For example: <code>#[payload.params.message.metadata.context]</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Protected Material Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectProtectedMaterial</code> on the agent response to detect known copyrighted text. Requires Moderate Response enabled.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-request timeout for each Azure Content Safety API call in milliseconds. Must be between 1000 and 30000. Default: <code>5000</code>.</p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Azure API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Streaming Min Buffer Chars</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Minimum number of characters accumulated across consecutive SSE frame bodies before the policy calls Azure for moderation. Must be between 1 and 8192. Default: <code>256</code>.</p></div></div></td></tr><tr><td><div><div><p>Max Payload Bytes</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum request-or-response body size (in bytes) that the policy will send to Azure. Must be between 1024 and 10000. Default: <code>10000</code>.</p></div></div></td></tr><tr><td><div><div><p>Sampling Rate Percent</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Percentage of sessions to sample for moderation. <code>100</code> (default) moderates every request; <code>50</code> moderates half of sessions; <code>0</code> disables moderation. Sampling is deterministic per session.</p></div></div></td></tr><tr><td><div><div><p>Session Key Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression resolving the session identifier used by the sampler. Defaults to <code>#[payload.params.message.contextId default payload.params.message.messageId]</code>. Only used when Sampling Rate Percent is less than 100.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Azure Content Guardrails policy integrates with Azure AI Content Safety to evaluate A2A
v1.0 agent messages and responses against configurable safety policies.

### Supported Methods

The policy runs only on these A2A v1.0 methods:

- `SendMessage`

- `SendStreamingMessage`

Read-only methods (`GetTask`, `ListTasks`, push-notification methods, `SubscribeToTask`,
`GetExtendedAgentCard`) and the agent-card endpoint pass through untouched. Non-A2A traffic also
passes through.

### Transport Support

The policy moderates these transports:

- **JSON-RPC** — Full moderation on request and response

- **HTTP+JSON** — Full moderation on request and response

**gRPC pass-through**: Requests and responses with `content-type: application/grpc` or
`application/grpc+proto` skip this policy entirely and pass through unchanged. If you need gRPC
moderation, route gRPC clients through an HTTP+JSON transcoder.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the raw request body.

    2.  The policy sends the body to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories (Hate, SelfHarm, Sexual, Violence) and checks
          blocklists

        - `text:shieldPrompt` — Detects jailbreak attempts and indirect injections (when
          `enablePromptShield` is enabled)

    3.  If the request violates any policies, the policy blocks the request and returns a `403`
        error code to the client.

    4.  If the request passes, the policy forwards the original request to the upstream agent.

2.  **Response Phase — Unary** (when `moderateResponse` is enabled):

    1.  The policy intercepts the agent response.

    2.  The policy sends the response body to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories and checks blocklists

        - `text:detectGroundedness` — Scores the response against the grounding source (when enabled
          and grounding source is available)

        - `text:detectProtectedMaterial` — Detects known copyrighted text (when enabled)

    3.  If the response violates any policies, the policy returns a `403` error code to the client.

    4.  If the response passes, the policy forwards the original response to the client.

3.  **Response Phase — Streaming** (when `moderateStreamingResponse` is enabled):

    1.  The policy installs a stream handler that receives decoded SSE frames.

    2.  Frame bodies are accumulated in a rolling buffer.

    3.  When the buffer reaches `streamingMinBufferChars`, it drains to `text:analyze` (and
        optionally `text:detectProtectedMaterial`).

    4.  If any rule fires, the policy replaces the current frame with a
        `TaskStatusUpdateEvent { state: FAILED }` and closes the stream.

    5.  On clean decisions, frames forward unchanged and the buffer resets.

### Whole-Payload Passing

The policy sends the **raw JSON body** (as bytes) to Azure as the `text` value, not extracted text
parts. This approach provides:

- **Complete coverage** — Adversarial content in any field reaches Azure

- **Simplicity** — No per-schema drift when A2A adds new part kinds

- **Consistency** — Works uniformly across JSON-RPC and HTTP+JSON

> [!NOTE] Azure limits inputs at ~10,000 characters. Larger payloads trigger the `payload_too_large`
> rule.

### Groundedness Detection

Groundedness detection helps detect hallucinations by evaluating whether agent responses are
grounded in the provided reference text. This is particularly useful for RAG (Retrieval-Augmented
Generation) applications.

To enable groundedness detection:

1.  Enable groundedness detection in Advanced Configuration (`enableGroundednessDetection: true`).

2.  Configure the **Grounding Source Selector** to extract the reference text from the request body.

3.  Set the API Version to a preview version that supports the groundedness endpoint (for example,
    `2024-09-15-preview`).

The grounding source selector is a DataWeave expression that extracts the reference text the agent
response should be based on (typically documents or context provided in the request).

Example Configuration

```yaml
advancedConfiguration:
  apiVersion: "2024-09-15-preview"
  enableGroundednessDetection: true
  groundingSourceSelector: "#[payload.params.message.metadata.context]"
```

### Severity Thresholds

Azure AI Content Safety evaluates content across four harm categories and assigns a severity level
to each:

- **0** — Safe (no harmful content detected)

- **2** — Low severity

- **4** — Medium severity

- **6** — High severity

The policy rejects content when the severity level is at or above the configured threshold:

<table><colgroup><col> <col></colgroup><thead><tr><th>Threshold Value</th><th>Content Blocked</th></tr></thead><tbody><tr><td><div><div><p>0</p></div></div></td><td><div><div><p>Any flagged content (severity &gt; 0) is blocked. This is the strictest setting.</p></div></div></td></tr><tr><td><div><div><p>2</p></div></div></td><td><div><div><p>Content with low, medium, or high severity is blocked. This is the recommended default.</p></div></div></td></tr><tr><td><div><div><p>4</p></div></div></td><td><div><div><p>Content with medium or high severity is blocked. This allows low-severity content.</p></div></div></td></tr><tr><td><div><div><p>6</p></div></div></td><td><div><div><p>Only high-severity content is blocked. This is the most permissive setting.</p></div></div></td></tr></tbody></table>

You can configure a default threshold that applies to all categories, and optionally override the
threshold for specific categories.

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-flex-azure-guardrails-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code>, <code>skip</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies. <code>skip</code> indicates the session was sampled out.</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-azure-guardrails-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code>, <code>response_stream</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the request or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-azure-guardrails-reason</code></p></div></div></td><td><div><div><p><code>severity_hate</code>, <code>severity_self_harm</code>, <code>severity_sexual</code>, <code>severity_violence</code>, <code>blocklist</code>, <code>prompt_shield</code>, <code>groundedness</code>, <code>protected_material</code>, <code>payload_too_large</code>, <code>streaming_buffer_overflow</code>, <code>service_unavailable</code>, <code>sampled_out</code></p></div></div></td><td><div><div><p>Why the content was rejected or skipped. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

Headers are not emitted on gRPC pass-through traffic.

## Response on Reject

When the policy blocks content, it returns a transport-appropriate error response.

### JSON-RPC Transport

HTTP 403 with a JSON-RPC 2.0 error response:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Request blocked by Azure Content Safety: severity_violence",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "severity_violence"
        }
      }
    ]
  }
}
```

The error code `-32600` maps to the A2A v1.0 `FORBIDDEN` reason code.

### HTTP+JSON Transport

HTTP 403 with a Google RPC Status error response:

```json
{
  "error": {
    "code": 403,
    "status": "PERMISSION_DENIED",
    "message": "Request blocked by Azure Content Safety: severity_violence",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "severity_violence"
        }
      }
    ]
  }
}
```

### Streaming Response

When a streaming response trips a rule mid-stream, the policy replaces the offending frame with a
failed-status event and closes the stream:

```none
event: status-update
data: {"jsonrpc":"2.0","id":"req-2","result":{"taskId":"task-abc","status":{"state":"FAILED","message":{"role":"agent","parts":[{"kind":"text","text":"Response blocked by Azure Content Safety: severity_hate,protected_material"}]}},"isFinal":true}}
```

No further frames are emitted.

## Error Handling

The policy provides two error handling modes to control behavior when Azure API calls fail or
timeout.

Fail Closed (Default)

When **Fail Open** is disabled, any Azure API error or timeout results in rejection with HTTP `503`
and a transport-appropriate error response.

- JSON-RPC Transport:

  ```json
  {
    "jsonrpc": "2.0",
    "id": null,
    "error": {
      "code": -32603,
      "message": "Azure Content Safety service unavailable",
      "data": [
        {
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
          "domain": "a2a-protocol.org",
          "reason": "UNAVAILABLE",
          "metadata": {
            "detail": "service_unavailable"
          }
        }
      ]
    }
  }
  ```

  The error code `-32603` maps to the A2A v1.0 `UNAVAILABLE` reason code.

- HTTP+JSON Transport:

  ```json
  {
    "error": {
      "code": 503,
      "status": "UNAVAILABLE",
      "message": "Azure Content Safety service unavailable",
      "details": [
        {
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
          "domain": "a2a-protocol.org",
          "reason": "UNAVAILABLE",
          "metadata": {
            "detail": "service_unavailable"
          }
        }
      ]
    }
  }
  ```

  The `x-flex-azure-guardrails-reason` header is set to `service_unavailable` for both transports.

Fail Open

When **Fail Open** is enabled, Azure API errors are logged but traffic continues without moderation.
The `x-flex-azure-guardrails-reason` header is still set to `service_unavailable` for observability,
allowing you to detect partial-coverage moderation in monitoring systems.

## Example Configurations

The following examples demonstrate common configuration patterns for the A2A v1 Azure Content
Guardrails policy.

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
```

### 50% Sampling for Cost Control

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    advancedConfiguration:
      samplingRatePercent: 50
```

Half the sessions (bucketed deterministically by `contextId`) are moderated; the other half pass
through with the `sampled_out` observability header.

### Strict Threshold with Blocklists

This example blocks any flagged content and applies custom blocklists:

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    moderateStreamingResponse: false
    defaultSeverityThreshold: 0
    advancedConfiguration:
      blocklistNames:
        - competitor-names
        - internal-codenames
```

### Per-Category Thresholds

This example applies different thresholds to different harm categories:

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 2
    advancedConfiguration:
      selfHarmSeverityThreshold: "4" # Allow low-severity SelfHarm discussion
      violenceSeverityThreshold: "0" # Block any flagged Violence
```

### With Groundedness Detection (Hallucination Detection)

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs-eastus.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 4
    advancedConfiguration:
      apiVersion: "2024-09-15-preview"
      enableGroundednessDetection: true
      groundingSourceSelector: "#[payload.params.message.metadata.context]"
      enableProtectedMaterialDetection: true
      blocklistNames:
        - my-blocklist
      apiTimeoutMs: 10000
      streamingMinBufferChars: 512
      failOpen: false
      samplingRatePercent: 25
      sessionKeySelector: "#[payload.params.message.metadata.userId]"
```

## See Also

- [Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)

- [Prompt Shield](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/jailbreak-detection)

- [Groundedness Detection](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/groundedness)

- [Azure Content Safety Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-azure-content-safety) (for LLM traffic)

- [Agent Policies](https://docs.mulesoft.com/gateway/1.13/agent-policies)

<!-- document id=e1ceb5bd7a66dbb6850929a227f79d66afcd56e12712a593857e428f0e0545b2 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-azure-guardrails.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, a2a, azure, content safety, guardrails, harm detection, jailbreak, hallucination
---

# A2A v1 Azure Content Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Azure Content Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates A2A v1 agent messages against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-azure-guardrails-release-notes">A2A v1 Azure Content Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates Azure Content Safety policies</p></td></tr><tr><td><p>503 - Service Unavailable: Azure API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The A2A v1 Azure Content Guardrails policy provides comprehensive content moderation for A2A v1.0
agent traffic by evaluating requests and responses against the Azure AI Content Safety service. The
policy integrates with
[Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)
to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across four categories (**Hate**,
  **SelfHarm**, **Sexual**, and **Violence**) with configurable severity thresholds (`0`, `2`, `4`,
  `6`).

- **Prompt Shield**: Detects jailbreak attempts and indirect prompt-injection attacks using Azure’s
  advanced detection capabilities.

- **Blocklists**: Blocks content matching Azure-managed custom blocklists you define in Azure
  Content Safety Studio.

- **Groundedness Detection**: Evaluates whether agent responses are grounded in provided reference
  text (hallucination detection for RAG applications).

- **Protected Material Detection**: Detects known copyrighted text in agent responses.

The policy operates across three A2A v1.0 transport protocols:

- **JSON-RPC** — Moderates `SendMessage` and `SendStreamingMessage` on both request and response

- **HTTP+JSON** — Moderates `POST /message:send` and streaming responses

- **gRPC** — Pass-through without moderation in v1.0

The policy operates in independent phases:

- **Request phase**: Moderates user messages before they reach the upstream agent, preventing
  harmful or inappropriate messages from being processed.

- **Response phase**: Moderates agent responses before they reach the client, ensuring outputs
  comply with safety policies.

- **Streaming response phase**: Best-effort moderation of streaming responses by buffering frame
  bodies and scanning on configurable thresholds.

When content violates safety policies, the request is rejected with a `403` error code and never
reaches the agent (request phase) or the client receives a `403` instead of the agent response
(response phase).

> [!NOTE] This policy is designed for A2A v1.0 traffic only. gRPC traffic passes through without
> moderation in this version.

## Before You Begin

Before configuring this policy, you need:

1.  **Azure Account** with access to Azure AI Content Safety

2.  **Azure Content Safety Resource** created in the Azure Portal

3.  **Subscription Key** from the Azure Portal (Keys and Endpoint section)

4.  **Resource Endpoint URL** from the Azure Portal configured as a Flex service

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Azure Content Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Azure Content Safety Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety endpoint base URL configured as a Flex service, for example, <code>https://&lt;resource&gt;.cognitiveservices.azure.com</code>. The policy appends endpoint paths at runtime.</p></div></div></td></tr><tr><td><div><div><p>Azure API Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety subscription key. The key is passed in the <code>Ocp-Apim-Subscription-Key</code> header and marked as sensitive.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the user message against Azure Content Safety before forwarding to the upstream agent. Rejected messages never reach the agent. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the agent response against Azure Content Safety before returning to the client. Rejected responses return <code>403</code> error code. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Moderate Streaming Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates streaming responses by buffering frame bodies and scanning on configurable thresholds. When disabled, streaming responses pass through unchanged. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Default Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Severity threshold applied to all four harm categories (Hate, SelfHarm, Sexual, Violence). Content with severity at or above this value is rejected. Supported values are <code>0</code>, <code>2</code> (default), <code>4</code>, and <code>6</code>.</p></div><div><p>For details, see <a href="#severity-thresholds">Severity Thresholds</a>.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>API Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Azure Content Safety API version used for all endpoint calls. Default: <code>2024-09-01</code>.</p></div><div><p>To enable Groundedness Detection, override this to a supported preview version, for example, <code>2024-09-15-preview</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Prompt Shield</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:shieldPrompt</code> alongside <code>text:analyze</code> on the request to detect jailbreak attempts and indirect prompt-injection attacks. Default: <code>true</code>.</p></div></div></td></tr><tr><td><div><div><p>Hate Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Hate harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>SelfHarm Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the SelfHarm harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Sexual Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Sexual harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Violence Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Violence harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Blocklist Names</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Names of Azure-managed blocklists (created in Azure Content Safety Studio) to evaluate against the input text.</p></div></div></td></tr><tr><td><div><div><p>Enable Groundedness Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectGroundedness</code> on the agent response to detect hallucinated statements. Requires Moderate Response enabled and Grounding Source Selector to be set. Only available in Azure regions that support the API, and only on preview API versions (for example, <code>2024-09-15-preview</code>).</p></div></div></td></tr><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression resolving the grounding source text from the canonical A2A request body. Required when Groundedness Detection is enabled. For example: <code>#[payload.params.message.metadata.context]</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Protected Material Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectProtectedMaterial</code> on the agent response to detect known copyrighted text. Requires Moderate Response enabled.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-request timeout for each Azure Content Safety API call in milliseconds. Must be between 1000 and 30000. Default: <code>5000</code>.</p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Azure API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Streaming Min Buffer Chars</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Minimum number of characters accumulated across consecutive SSE frame bodies before the policy calls Azure for moderation. Must be between 1 and 8192. Default: <code>256</code>.</p></div></div></td></tr><tr><td><div><div><p>Max Payload Bytes</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum request-or-response body size (in bytes) that the policy will send to Azure. Must be between 1024 and 10000. Default: <code>10000</code>.</p></div></div></td></tr><tr><td><div><div><p>Sampling Rate Percent</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Percentage of sessions to sample for moderation. <code>100</code> (default) moderates every request; <code>50</code> moderates half of sessions; <code>0</code> disables moderation. Sampling is deterministic per session.</p></div></div></td></tr><tr><td><div><div><p>Session Key Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression resolving the session identifier used by the sampler. Defaults to <code>#[payload.params.message.contextId default payload.params.message.messageId]</code>. Only used when Sampling Rate Percent is less than 100.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Azure Content Guardrails policy integrates with Azure AI Content Safety to evaluate A2A
v1.0 agent messages and responses against configurable safety policies.

### Supported Methods

The policy runs only on these A2A v1.0 methods:

- `SendMessage`

- `SendStreamingMessage`

Read-only methods (`GetTask`, `ListTasks`, push-notification methods, `SubscribeToTask`,
`GetExtendedAgentCard`) and the agent-card endpoint pass through untouched. Non-A2A traffic also
passes through.

### Transport Support

The policy moderates these transports:

- **JSON-RPC** — Full moderation on request and response

- **HTTP+JSON** — Full moderation on request and response

**gRPC pass-through**: Requests and responses with `content-type: application/grpc` or
`application/grpc+proto` skip this policy entirely and pass through unchanged. If you need gRPC
moderation, route gRPC clients through an HTTP+JSON transcoder.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the raw request body.

    2.  The policy sends the body to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories (Hate, SelfHarm, Sexual, Violence) and checks
          blocklists

        - `text:shieldPrompt` — Detects jailbreak attempts and indirect injections (when
          `enablePromptShield` is enabled)

    3.  If the request violates any policies, the policy blocks the request and returns a `403`
        error code to the client.

    4.  If the request passes, the policy forwards the original request to the upstream agent.

2.  **Response Phase — Unary** (when `moderateResponse` is enabled):

    1.  The policy intercepts the agent response.

    2.  The policy sends the response body to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories and checks blocklists

        - `text:detectGroundedness` — Scores the response against the grounding source (when enabled
          and grounding source is available)

        - `text:detectProtectedMaterial` — Detects known copyrighted text (when enabled)

    3.  If the response violates any policies, the policy returns a `403` error code to the client.

    4.  If the response passes, the policy forwards the original response to the client.

3.  **Response Phase — Streaming** (when `moderateStreamingResponse` is enabled):

    1.  The policy installs a stream handler that receives decoded SSE frames.

    2.  Frame bodies are accumulated in a rolling buffer.

    3.  When the buffer reaches `streamingMinBufferChars`, it drains to `text:analyze` (and
        optionally `text:detectProtectedMaterial`).

    4.  If any rule fires, the policy replaces the current frame with a
        `TaskStatusUpdateEvent { state: FAILED }` and closes the stream.

    5.  On clean decisions, frames forward unchanged and the buffer resets.

### Whole-Payload Passing

The policy sends the **raw JSON body** (as bytes) to Azure as the `text` value, not extracted text
parts. This approach provides:

- **Complete coverage** — Adversarial content in any field reaches Azure

- **Simplicity** — No per-schema drift when A2A adds new part kinds

- **Consistency** — Works uniformly across JSON-RPC and HTTP+JSON

> [!NOTE] Azure limits inputs at ~10,000 characters. Larger payloads trigger the `payload_too_large`
> rule.

### Groundedness Detection

Groundedness detection helps detect hallucinations by evaluating whether agent responses are
grounded in the provided reference text. This is particularly useful for RAG (Retrieval-Augmented
Generation) applications.

To enable groundedness detection:

1.  Enable groundedness detection in Advanced Configuration (`enableGroundednessDetection: true`).

2.  Configure the **Grounding Source Selector** to extract the reference text from the request body.

3.  Set the API Version to a preview version that supports the groundedness endpoint (for example,
    `2024-09-15-preview`).

The grounding source selector is a DataWeave expression that extracts the reference text the agent
response should be based on (typically documents or context provided in the request).

Example Configuration

```yaml
advancedConfiguration:
  apiVersion: "2024-09-15-preview"
  enableGroundednessDetection: true
  groundingSourceSelector: "#[payload.params.message.metadata.context]"
```

### Severity Thresholds

Azure AI Content Safety evaluates content across four harm categories and assigns a severity level
to each:

- **0** — Safe (no harmful content detected)

- **2** — Low severity

- **4** — Medium severity

- **6** — High severity

The policy rejects content when the severity level is at or above the configured threshold:

<table><colgroup><col> <col></colgroup><thead><tr><th>Threshold Value</th><th>Content Blocked</th></tr></thead><tbody><tr><td><div><div><p>0</p></div></div></td><td><div><div><p>Any flagged content (severity &gt; 0) is blocked. This is the strictest setting.</p></div></div></td></tr><tr><td><div><div><p>2</p></div></div></td><td><div><div><p>Content with low, medium, or high severity is blocked. This is the recommended default.</p></div></div></td></tr><tr><td><div><div><p>4</p></div></div></td><td><div><div><p>Content with medium or high severity is blocked. This allows low-severity content.</p></div></div></td></tr><tr><td><div><div><p>6</p></div></div></td><td><div><div><p>Only high-severity content is blocked. This is the most permissive setting.</p></div></div></td></tr></tbody></table>

You can configure a default threshold that applies to all categories, and optionally override the
threshold for specific categories.

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-flex-azure-guardrails-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code>, <code>skip</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies. <code>skip</code> indicates the session was sampled out.</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-azure-guardrails-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code>, <code>response_stream</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the request or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-azure-guardrails-reason</code></p></div></div></td><td><div><div><p><code>severity_hate</code>, <code>severity_self_harm</code>, <code>severity_sexual</code>, <code>severity_violence</code>, <code>blocklist</code>, <code>prompt_shield</code>, <code>groundedness</code>, <code>protected_material</code>, <code>payload_too_large</code>, <code>streaming_buffer_overflow</code>, <code>service_unavailable</code>, <code>sampled_out</code></p></div></div></td><td><div><div><p>Why the content was rejected or skipped. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

Headers are not emitted on gRPC pass-through traffic.

## Response on Reject

When the policy blocks content, it returns a transport-appropriate error response.

### JSON-RPC Transport

HTTP 403 with a JSON-RPC 2.0 error response:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Request blocked by Azure Content Safety: severity_violence",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "severity_violence"
        }
      }
    ]
  }
}
```

The error code `-32600` maps to the A2A v1.0 `FORBIDDEN` reason code.

### HTTP+JSON Transport

HTTP 403 with a Google RPC Status error response:

```json
{
  "error": {
    "code": 403,
    "status": "PERMISSION_DENIED",
    "message": "Request blocked by Azure Content Safety: severity_violence",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "severity_violence"
        }
      }
    ]
  }
}
```

### Streaming Response

When a streaming response trips a rule mid-stream, the policy replaces the offending frame with a
failed-status event and closes the stream:

```none
event: status-update
data: {"jsonrpc":"2.0","id":"req-2","result":{"taskId":"task-abc","status":{"state":"FAILED","message":{"role":"agent","parts":[{"kind":"text","text":"Response blocked by Azure Content Safety: severity_hate,protected_material"}]}},"isFinal":true}}
```

No further frames are emitted.

## Error Handling

The policy provides two error handling modes to control behavior when Azure API calls fail or
timeout.

Fail Closed (Default)

When **Fail Open** is disabled, any Azure API error or timeout results in rejection with HTTP `503`
and a transport-appropriate error response.

- JSON-RPC Transport:

  ```json
  {
    "jsonrpc": "2.0",
    "id": null,
    "error": {
      "code": -32603,
      "message": "Azure Content Safety service unavailable",
      "data": [
        {
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
          "domain": "a2a-protocol.org",
          "reason": "UNAVAILABLE",
          "metadata": {
            "detail": "service_unavailable"
          }
        }
      ]
    }
  }
  ```

  The error code `-32603` maps to the A2A v1.0 `UNAVAILABLE` reason code.

- HTTP+JSON Transport:

  ```json
  {
    "error": {
      "code": 503,
      "status": "UNAVAILABLE",
      "message": "Azure Content Safety service unavailable",
      "details": [
        {
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",
          "domain": "a2a-protocol.org",
          "reason": "UNAVAILABLE",
          "metadata": {
            "detail": "service_unavailable"
          }
        }
      ]
    }
  }
  ```

  The `x-flex-azure-guardrails-reason` header is set to `service_unavailable` for both transports.

Fail Open

When **Fail Open** is enabled, Azure API errors are logged but traffic continues without moderation.
The `x-flex-azure-guardrails-reason` header is still set to `service_unavailable` for observability,
allowing you to detect partial-coverage moderation in monitoring systems.

## Example Configurations

The following examples demonstrate common configuration patterns for the A2A v1 Azure Content
Guardrails policy.

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
```

### 50% Sampling for Cost Control

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    advancedConfiguration:
      samplingRatePercent: 50
```

Half the sessions (bucketed deterministically by `contextId`) are moderated; the other half pass
through with the `sampled_out` observability header.

### Strict Threshold with Blocklists

This example blocks any flagged content and applies custom blocklists:

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    moderateStreamingResponse: false
    defaultSeverityThreshold: 0
    advancedConfiguration:
      blocklistNames:
        - competitor-names
        - internal-codenames
```

### Per-Category Thresholds

This example applies different thresholds to different harm categories:

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 2
    advancedConfiguration:
      selfHarmSeverityThreshold: "4" # Allow low-severity SelfHarm discussion
      violenceSeverityThreshold: "0" # Block any flagged Violence
```

### With Groundedness Detection (Hallucination Detection)

```yaml
- policyRef:
    name: a2a-v1-azure-guardrails-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs-eastus.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 4
    advancedConfiguration:
      apiVersion: "2024-09-15-preview"
      enableGroundednessDetection: true
      groundingSourceSelector: "#[payload.params.message.metadata.context]"
      enableProtectedMaterialDetection: true
      blocklistNames:
        - my-blocklist
      apiTimeoutMs: 10000
      streamingMinBufferChars: 512
      failOpen: false
      samplingRatePercent: 25
      sessionKeySelector: "#[payload.params.message.metadata.userId]"
```

## See Also

- [Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)

- [Prompt Shield](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/jailbreak-detection)

- [Groundedness Detection](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/groundedness)

- [Azure Content Safety Policy](https://docs.mulesoft.com/gateway/latest/policies-included-azure-content-safety) (for LLM traffic)

- [Agent Policies](https://docs.mulesoft.com/gateway/latest/agent-policies)

<!-- document id=5723399867c67a96bdcd67b0d96f74c683ceb0b3276a177c267660957e624cfd url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-bedrock-guardrails.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, a2a, agent, bedrock, guardrails, content safety, pii
---

# A2A v1 Bedrock Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Bedrock Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-bedrock-guardrails-release-notes">A2A v1 Bedrock Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates guardrail policies</p></td></tr><tr><td><p>503 - Service Unavailable: Bedrock API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The A2A v1 Bedrock Guardrails policy provides comprehensive content moderation for A2A v1.0
(Agent-to-Agent) traffic by evaluating the entire request and response payloads against Amazon
Bedrock guardrails. This policy works with both JSON-RPC and HTTP+JSON transports.

The policy integrates with AWS Bedrock’s [Guardrails](https://aws.amazon.com/bedrock/guardrails/)
feature to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across six categories (hate, insults,
  sexual, violence, misconduct, prompt attacks) with configurable filter strengths (NONE, LOW,
  MEDIUM, HIGH).

- **Denied topics**: Blocks content related to specific topics you define, for example, financial
  advice, medical diagnosis

- **Word filters**: Blocks profanity and custom words or phrases you specify

- **PII detection**: Detects and optionally redacts personally identifiable information, for
  example, names, addresses, SSNs, credit cards

- **Contextual grounding**: Evaluates whether agent responses are grounded in provided reference
  text and relevant to the user query (hallucination detection)

The policy enforces the rules you configure for the specific guardrail in AWS.

The policy operates in two independent phases:

- **Request phase** — Moderates user messages before they reach the upstream agent, preventing
  harmful or inappropriate prompts from being processed.

- **Response phase** — Moderates agent responses before they reach the client, ensuring outputs
  comply with safety policies. Streaming responses (`text/event-stream`) aren’t moderated in v1.

When content violates guardrail policies, the request is rejected with a `403` error code and never
reaches the upstream agent (request phase) or the client receives a `403` instead of the agent
response (response phase).

## Before You Begin

Before configuring this policy, you need:

1.  **AWS Account** with access to Amazon Bedrock

2.  **Bedrock Guardrail** created and configured in AWS Console

3.  **IAM Credentials** with permissions to call `bedrock:ApplyGuardrail`

4.  **Guardrail ID** from the AWS Console

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Bedrock Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Bedrock Runtime Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Amazon Bedrock Runtime endpoint URL. Accepts either:</p></div><div><ul><li><p>Base host: <code>https://bedrock-runtime.us-east-1.amazonaws.com</code></p></li><li><p>Full ApplyGuardrail URL: <code>https://bedrock-runtime.us-east-2.amazonaws.com/guardrail/&lt;id&gt;/version/&lt;version&gt;/apply</code></p></li></ul></div><div><p>When the full URL is provided, the policy derives the region, guardrail identifier, and guardrail version, unless if you explicitly configure those values.</p></div></div></td></tr><tr><td><div><div><p>AWS Credentials</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS credentials and region for signing requests to the Bedrock API. See <a href="#aws-credentials">AWS Credentials</a>.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Identifier</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>The unique ID of the Bedrock guardrail to apply (for example, <code>paccgfhgnj1dc</code>).</p></div><div><p>Required unless provided in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Version of the guardrail to apply.</p></div><div><ul><li><p><code>DRAFT</code> (default): Use the working draft version for development and testing.</p></li><li><p>Numeric version (for example, <code>"1"</code>, <code>"2"</code>): Use a published version for production deployments.</p></li></ul></div><div><p>Required unless provided in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default: <code>true</code>), the policy evaluates the entire request body against the guardrail before forwarding to the upstream agent. Rejected requests never reach the agent.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default: <code>true</code>), the policy evaluates the entire unary response body against the guardrail before returning to the client. Rejected responses return a <code>403</code> error code. Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr></tbody></table>

### AWS Credentials

The policy uses AWS Signature V4 to authenticate with the Bedrock API and supports both long-lived
IAM credentials and temporary STS credentials.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Access Key ID</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS access key ID, either:</p></div><div><ul><li><p>Long-lived IAM user credentials (starting with <code>AKIA</code>)</p></li><li><p>Temporary credentials from STS or SSO (starting with <code>ASIA</code>)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Secret Access Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS secret access key corresponding to the Access Key ID.</p></div></div></td></tr><tr><td><div><div><p>Session Token</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>Required when using temporary credentials (Access Key ID starting with <code>ASIA</code>). Leave empty for long-lived IAM user credentials.</p></div></div></td></tr><tr><td><div><div><p>Region</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>AWS region of the Bedrock Runtime endpoint (for example, <code>us-east-1</code>).</p></div><div><p>Set explicitly for custom domains or VPC endpoints. Optional when the region is provided in the Bedrock Runtime Endpoint host.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the reference text for contextual grounding from the request body.</p></div><div><p>Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with <strong>Grounding Query Selector</strong>.</p></div><div><p>Example for JSON-RPC: <code>#[payload.params.message.metadata.context]</code></p></div><div><p>Example for HTTP+JSON: <code>#[payload.message.metadata.context]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Grounding Query Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the user query for contextual grounding from the request body.</p></div><div><p>Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with <strong>Grounding Source Selector</strong>.</p></div><div><p>Example for JSON-RPC: <code>#[payload.params.message.parts[0].text]</code></p></div><div><p>Example for HTTP+JSON: <code>#[payload.message.parts[0].text]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Max Payload Bytes</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum request or response body size (in bytes) sent to Bedrock.</p></div><div><ul><li><p>Default: <code>25000</code></p></li><li><p>Range: <code>1024</code> - <code>25000</code></p></li></ul></div><div><p>The <code>ApplyGuardrail</code> API caps synchronous calls at approximately 25,000 characters. Larger payloads are rejected (when fail-open is disabled) or passed through without moderation (when fail-open is enabled).</p></div></div></td></tr><tr><td><div><div><p>Sampling Rate Percent</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Percentage of sessions to sample for moderation (0-100).</p></div><div><ul><li><p>Default: <code>100</code> (moderate every request)</p></li><li><p><code>50</code>: Moderate half of sessions</p></li><li><p><code>0</code>: Disable moderation</p></li></ul></div><div><p>Sampling is deterministic per session. The same session is always or never sampled.</p></div></div></td></tr><tr><td><div><div><p>Session Key Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the session identifier used for sampling.</p></div><div><p>By default, the key selector resolves to A2A v1.0 <code>contextId</code> (conversation-scoped identifier). For single messages that aren’t part of an ongoing A2A conversation (one-shot sends), the key selector resolves to <code>messageId</code>.</p></div><div><p>Only used when Sampling Rate Percent is less than 100.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Timeout in milliseconds for calls to the Bedrock <code>ApplyGuardrail</code> API.</p></div><div><ul><li><p>Default: <code>5000</code></p></li><li><p>Range: <code>1000</code> - <code>30000</code></p></li></ul></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Bedrock API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div><div><p>When enabled, failures are logged and the <code>service_unavailable</code> reason is emitted in response headers for observability.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Bedrock Guardrails policy integrates with AWS Bedrock’s content moderation service to
evaluate complete A2A request and response payloads against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for requests and responses. The two phases mirror AWS
Bedrock’s INPUT and OUTPUT scopes:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the entire request body.

    2.  The policy sends the complete JSON payload to Bedrock’s `ApplyGuardrail` API.

    3.  If the content violates any guardrail policies, the policy blocks the request and returns a
        `403` error code to the client.

    4.  If the content passes, the policy forwards the original request to the upstream agent.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the agent response.

    2.  The policy sends the complete response to Bedrock’s `ApplyGuardrail` API.

    3.  If the response violates any guardrail policies, the policy returns a `403` error code to
        the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation. Only non-streaming (`application/json`) responses are moderated.

### Supported Transports

The policy supports these A2A v1.0 transports:

- **JSON-RPC**

- **HTTP+JSON**

The policy doesn’t support gRPC traffic (`application/grpc` or `application/grpc+proto`) and it
passes through without moderation. When gRPC traffic is detected, the policy emits these
observability headers:

- `x-flex-bedrock-guardrails-action: skip`

- `x-flex-bedrock-guardrails-reason: unsupported_transport_v1`

### Method Scope

The policy only evaluates `SendMessage` and `SendStreamingMessage` methods. Other methods (for
example, `GetTask`, `ListTasks`, `SubscribeToTask`, agent card requests) pass through without
moderation.

### Contextual Grounding

Contextual grounding helps detect hallucinations by scoring agent responses on two dimensions:

- **Grounding**: Is the response derived from the provided reference text?

- **Relevance**: Does the response actually answer the user’s question?

To enable contextual grounding:

1.  Enable the contextual grounding feature for your AWS Bedrock guardrail.

2.  Configure both **Grounding Source Selector** and **Grounding Query Selector** in the policy.

The selectors are DataWeave expressions that extract:

- **Grounding source**: The reference text the answer should be based on (often from message
  metadata or context)

- **Query**: The user’s actual question (often from message parts)

Both parameters must be configured together. Configuring only one causes the Bedrock API to return a
`400` error code.

DataWeave selectors bind to the raw request body differently for different transports:

- JSON-RPC

  For JSON-RPC, A2A parameters are under `payload.params.*`. For example:

  ```yaml
  advancedConfiguration:
    groundingSourceSelector: "#[payload.params.message.metadata.context]"
    groundingQuerySelector: "#[payload.params.message.parts[0].text]"
  ```

- HTTP+JSON

  For HTTP+JSON, A2A parameters are at the top level (`payload.*`). For example:

  ```yaml
  advancedConfiguration:
    groundingSourceSelector: "#[payload.message.metadata.context]"
    groundingQuerySelector: "#[payload.message.parts[0].text]"
  ```

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-flex-bedrock-guardrails-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code>, <code>skip</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies. <code>skip</code> indicates the request wasn’t moderated (sampling, gRPC, or streaming).</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-bedrock-guardrails-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the request or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-bedrock-guardrails-reason</code></p></div></div></td><td><div><div><p><code>content_filter</code>, <code>denied_topic</code>, <code>word_filter</code>, <code>pii</code>, <code>grounding</code>, <code>payload_too_large</code>, <code>service_unavailable</code>, <code>sampled_out</code>, <code>unsupported_transport_v1</code></p></div></div></td><td><div><div><p>Why the content was rejected or skipped. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: "${GUARDRAIL_IDENTIFIER}"
    guardrailVersion: "1"
```

### Using Full URL (Region, ID, and Version Derived)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-2.amazonaws.com/guardrail/2dxe6otc16kv/version/DRAFT/apply
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
```

### Request-Only Moderation (Block Harmful Prompts)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: false
```

### With Contextual Grounding (Hallucination Detection)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      sessionToken: "${AWS_SESSION_TOKEN}" # for temporary credentials
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: DRAFT
    moderateRequest: false
    moderateResponse: true
    advancedConfiguration:
      groundingSourceSelector: "#[payload.params.message.metadata.context]"
      groundingQuerySelector: "#[payload.params.message.parts[0].text]"
      apiTimeoutMs: 8000
      failOpen: false
```

### Fail-Open Configuration with Sampling (High Availability, Cost Control)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: true
    advancedConfiguration:
      failOpen: true # Allow traffic if Bedrock is unavailable
      apiTimeoutMs: 3000
      samplingRatePercent: 50 # Moderate 50% of sessions
```

## Error Responses

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Condition</th><th>Status Code</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Content violates guardrail (request phase)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Request blocked before reaching the agent. Response body contains A2A error envelope with reason details.</p></div></div></td></tr><tr><td><div><div><p>Content violates guardrail (response phase)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Response blocked and replaced with A2A error envelope. Original response is not returned.</p></div></div></td></tr><tr><td><div><div><p>Bedrock API failure (fail-open disabled)</p></div></div></td><td><div><div><p>503 Service Unavailable</p></div></div></td><td><div><div><p>Bedrock service error or timeout with fail-open disabled. Traffic is blocked.</p></div></div></td></tr><tr><td><div><div><p>Bedrock API failure (fail-open enabled)</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Traffic proceeds unmoderated. Observability headers indicate <code>service_unavailable</code>.</p></div></div></td></tr><tr><td><div><div><p>Payload exceeds size limit (fail-open disabled)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Payload larger than <code>maxPayloadBytes</code>. Request blocked.</p></div></div></td></tr><tr><td><div><div><p>Payload exceeds size limit (fail-open enabled)</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Oversized payload passes through unmoderated. Observability headers indicate <code>payload_too_large</code>.</p></div></div></td></tr><tr><td><div><div><p>Sampled-out session</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Session not selected for moderation. Traffic passes through with <code>sampled_out</code> reason header.</p></div></div></td></tr><tr><td><div><div><p>gRPC traffic</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>gRPC traffic passes through unmoderated with <code>unsupported_transport_v1</code> reason header.</p></div></div></td></tr></tbody></table>

## Limitations

- **Streaming responses**: Streaming responses (`text/event-stream`) aren’t moderated and pass
  through unchanged.

- **gRPC traffic**: gRPC traffic isn’t moderated and passes through with observability headers.

- **Payload size**: Payloads exceeding `maxPayloadBytes` (default 25,000 bytes) can’t be evaluated
  synchronously by Bedrock.

- **JSON envelope**: Bedrock evaluates the complete JSON payload, including A2A protocol fields, not
  just the natural language content. This may affect classifier confidence scores compared to
  evaluating bare text.

## Best Practices

1.  **Use versioned guardrails in production**: Pin to a numeric guardrail version instead of
    `DRAFT` for consistent, repeatable behavior.

2.  **Monitor observability headers**: Track `x-flex-bedrock-guardrails-reason` headers to
    understand why content is blocked or skipped.

3.  **Start with sampling in production**: Use `samplingRatePercent: 50` or lower initially to
    control costs while establishing baseline behavior.

4.  **Enable fail-open for availability**: Consider `failOpen: true` in production to prevent
    Bedrock outages from blocking all agent traffic.

5.  **Test grounding with representative payloads**: If using contextual grounding, validate with
    full A2A JSON payloads, not just extracted text fields.

6.  **Use temporary credentials**: Rotate temporary STS credentials instead of long-lived IAM keys
    for improved security.

## See Also

- [Amazon Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) - AWS documentation

- [ApplyGuardrail API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html) -
  AWS API documentation

- [Amazon Bedrock Guardrails Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-bedrock-guardrails) - LLM Gateway version

- [A2A v1 PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-pii-detector) - Alternative PII detection
  for A2A v1.0

<!-- document id=9725d8ebda79cc82ded504f076549fbcfcd86fdfcea30a1359878436c9175eb6 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-bedrock-guardrails.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, a2a, agent, bedrock, guardrails, content safety, pii
---

# A2A v1 Bedrock Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Bedrock Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-bedrock-guardrails-release-notes">A2A v1 Bedrock Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates guardrail policies</p></td></tr><tr><td><p>503 - Service Unavailable: Bedrock API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The A2A v1 Bedrock Guardrails policy provides comprehensive content moderation for A2A v1.0
(Agent-to-Agent) traffic by evaluating the entire request and response payloads against Amazon
Bedrock guardrails. This policy works with both JSON-RPC and HTTP+JSON transports.

The policy integrates with AWS Bedrock’s [Guardrails](https://aws.amazon.com/bedrock/guardrails/)
feature to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across six categories (hate, insults,
  sexual, violence, misconduct, prompt attacks) with configurable filter strengths (NONE, LOW,
  MEDIUM, HIGH).

- **Denied topics**: Blocks content related to specific topics you define, for example, financial
  advice, medical diagnosis

- **Word filters**: Blocks profanity and custom words or phrases you specify

- **PII detection**: Detects and optionally redacts personally identifiable information, for
  example, names, addresses, SSNs, credit cards

- **Contextual grounding**: Evaluates whether agent responses are grounded in provided reference
  text and relevant to the user query (hallucination detection)

The policy enforces the rules you configure for the specific guardrail in AWS.

The policy operates in two independent phases:

- **Request phase** — Moderates user messages before they reach the upstream agent, preventing
  harmful or inappropriate prompts from being processed.

- **Response phase** — Moderates agent responses before they reach the client, ensuring outputs
  comply with safety policies. Streaming responses (`text/event-stream`) aren’t moderated in v1.

When content violates guardrail policies, the request is rejected with a `403` error code and never
reaches the upstream agent (request phase) or the client receives a `403` instead of the agent
response (response phase).

## Before You Begin

Before configuring this policy, you need:

1.  **AWS Account** with access to Amazon Bedrock

2.  **Bedrock Guardrail** created and configured in AWS Console

3.  **IAM Credentials** with permissions to call `bedrock:ApplyGuardrail`

4.  **Guardrail ID** from the AWS Console

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Bedrock Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Bedrock Runtime Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Amazon Bedrock Runtime endpoint URL. Accepts either:</p></div><div><ul><li><p>Base host: <code>https://bedrock-runtime.us-east-1.amazonaws.com</code></p></li><li><p>Full ApplyGuardrail URL: <code>https://bedrock-runtime.us-east-2.amazonaws.com/guardrail/&lt;id&gt;/version/&lt;version&gt;/apply</code></p></li></ul></div><div><p>When the full URL is provided, the policy derives the region, guardrail identifier, and guardrail version, unless if you explicitly configure those values.</p></div></div></td></tr><tr><td><div><div><p>AWS Credentials</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS credentials and region for signing requests to the Bedrock API. See <a href="#aws-credentials">AWS Credentials</a>.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Identifier</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>The unique ID of the Bedrock guardrail to apply (for example, <code>paccgfhgnj1dc</code>).</p></div><div><p>Required unless provided in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Version of the guardrail to apply.</p></div><div><ul><li><p><code>DRAFT</code> (default): Use the working draft version for development and testing.</p></li><li><p>Numeric version (for example, <code>"1"</code>, <code>"2"</code>): Use a published version for production deployments.</p></li></ul></div><div><p>Required unless provided in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default: <code>true</code>), the policy evaluates the entire request body against the guardrail before forwarding to the upstream agent. Rejected requests never reach the agent.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default: <code>true</code>), the policy evaluates the entire unary response body against the guardrail before returning to the client. Rejected responses return a <code>403</code> error code. Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr></tbody></table>

### AWS Credentials

The policy uses AWS Signature V4 to authenticate with the Bedrock API and supports both long-lived
IAM credentials and temporary STS credentials.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Access Key ID</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS access key ID, either:</p></div><div><ul><li><p>Long-lived IAM user credentials (starting with <code>AKIA</code>)</p></li><li><p>Temporary credentials from STS or SSO (starting with <code>ASIA</code>)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Secret Access Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS secret access key corresponding to the Access Key ID.</p></div></div></td></tr><tr><td><div><div><p>Session Token</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>Required when using temporary credentials (Access Key ID starting with <code>ASIA</code>). Leave empty for long-lived IAM user credentials.</p></div></div></td></tr><tr><td><div><div><p>Region</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>AWS region of the Bedrock Runtime endpoint (for example, <code>us-east-1</code>).</p></div><div><p>Set explicitly for custom domains or VPC endpoints. Optional when the region is provided in the Bedrock Runtime Endpoint host.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the reference text for contextual grounding from the request body.</p></div><div><p>Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with <strong>Grounding Query Selector</strong>.</p></div><div><p>Example for JSON-RPC: <code>#[payload.params.message.metadata.context]</code></p></div><div><p>Example for HTTP+JSON: <code>#[payload.message.metadata.context]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Grounding Query Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the user query for contextual grounding from the request body.</p></div><div><p>Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with <strong>Grounding Source Selector</strong>.</p></div><div><p>Example for JSON-RPC: <code>#[payload.params.message.parts[0].text]</code></p></div><div><p>Example for HTTP+JSON: <code>#[payload.message.parts[0].text]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Max Payload Bytes</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum request or response body size (in bytes) sent to Bedrock.</p></div><div><ul><li><p>Default: <code>25000</code></p></li><li><p>Range: <code>1024</code> - <code>25000</code></p></li></ul></div><div><p>The <code>ApplyGuardrail</code> API caps synchronous calls at approximately 25,000 characters. Larger payloads are rejected (when fail-open is disabled) or passed through without moderation (when fail-open is enabled).</p></div></div></td></tr><tr><td><div><div><p>Sampling Rate Percent</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Percentage of sessions to sample for moderation (0-100).</p></div><div><ul><li><p>Default: <code>100</code> (moderate every request)</p></li><li><p><code>50</code>: Moderate half of sessions</p></li><li><p><code>0</code>: Disable moderation</p></li></ul></div><div><p>Sampling is deterministic per session. The same session is always or never sampled.</p></div></div></td></tr><tr><td><div><div><p>Session Key Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the session identifier used for sampling.</p></div><div><p>By default, the key selector resolves to A2A v1.0 <code>contextId</code> (conversation-scoped identifier). For single messages that aren’t part of an ongoing A2A conversation (one-shot sends), the key selector resolves to <code>messageId</code>.</p></div><div><p>Only used when Sampling Rate Percent is less than 100.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Timeout in milliseconds for calls to the Bedrock <code>ApplyGuardrail</code> API.</p></div><div><ul><li><p>Default: <code>5000</code></p></li><li><p>Range: <code>1000</code> - <code>30000</code></p></li></ul></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Bedrock API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div><div><p>When enabled, failures are logged and the <code>service_unavailable</code> reason is emitted in response headers for observability.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Bedrock Guardrails policy integrates with AWS Bedrock’s content moderation service to
evaluate complete A2A request and response payloads against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for requests and responses. The two phases mirror AWS
Bedrock’s INPUT and OUTPUT scopes:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the entire request body.

    2.  The policy sends the complete JSON payload to Bedrock’s `ApplyGuardrail` API.

    3.  If the content violates any guardrail policies, the policy blocks the request and returns a
        `403` error code to the client.

    4.  If the content passes, the policy forwards the original request to the upstream agent.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the agent response.

    2.  The policy sends the complete response to Bedrock’s `ApplyGuardrail` API.

    3.  If the response violates any guardrail policies, the policy returns a `403` error code to
        the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation. Only non-streaming (`application/json`) responses are moderated.

### Supported Transports

The policy supports these A2A v1.0 transports:

- **JSON-RPC**

- **HTTP+JSON**

The policy doesn’t support gRPC traffic (`application/grpc` or `application/grpc+proto`) and it
passes through without moderation. When gRPC traffic is detected, the policy emits these
observability headers:

- `x-flex-bedrock-guardrails-action: skip`

- `x-flex-bedrock-guardrails-reason: unsupported_transport_v1`

### Method Scope

The policy only evaluates `SendMessage` and `SendStreamingMessage` methods. Other methods (for
example, `GetTask`, `ListTasks`, `SubscribeToTask`, agent card requests) pass through without
moderation.

### Contextual Grounding

Contextual grounding helps detect hallucinations by scoring agent responses on two dimensions:

- **Grounding**: Is the response derived from the provided reference text?

- **Relevance**: Does the response actually answer the user’s question?

To enable contextual grounding:

1.  Enable the contextual grounding feature for your AWS Bedrock guardrail.

2.  Configure both **Grounding Source Selector** and **Grounding Query Selector** in the policy.

The selectors are DataWeave expressions that extract:

- **Grounding source**: The reference text the answer should be based on (often from message
  metadata or context)

- **Query**: The user’s actual question (often from message parts)

Both parameters must be configured together. Configuring only one causes the Bedrock API to return a
`400` error code.

DataWeave selectors bind to the raw request body differently for different transports:

- JSON-RPC

  For JSON-RPC, A2A parameters are under `payload.params.*`. For example:

  ```yaml
  advancedConfiguration:
    groundingSourceSelector: "#[payload.params.message.metadata.context]"
    groundingQuerySelector: "#[payload.params.message.parts[0].text]"
  ```

- HTTP+JSON

  For HTTP+JSON, A2A parameters are at the top level (`payload.*`). For example:

  ```yaml
  advancedConfiguration:
    groundingSourceSelector: "#[payload.message.metadata.context]"
    groundingQuerySelector: "#[payload.message.parts[0].text]"
  ```

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-flex-bedrock-guardrails-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code>, <code>skip</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies. <code>skip</code> indicates the request wasn’t moderated (sampling, gRPC, or streaming).</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-bedrock-guardrails-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the request or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-bedrock-guardrails-reason</code></p></div></div></td><td><div><div><p><code>content_filter</code>, <code>denied_topic</code>, <code>word_filter</code>, <code>pii</code>, <code>grounding</code>, <code>payload_too_large</code>, <code>service_unavailable</code>, <code>sampled_out</code>, <code>unsupported_transport_v1</code></p></div></div></td><td><div><div><p>Why the content was rejected or skipped. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: "${GUARDRAIL_IDENTIFIER}"
    guardrailVersion: "1"
```

### Using Full URL (Region, ID, and Version Derived)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-2.amazonaws.com/guardrail/2dxe6otc16kv/version/DRAFT/apply
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
```

### Request-Only Moderation (Block Harmful Prompts)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: false
```

### With Contextual Grounding (Hallucination Detection)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      sessionToken: "${AWS_SESSION_TOKEN}" # for temporary credentials
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: DRAFT
    moderateRequest: false
    moderateResponse: true
    advancedConfiguration:
      groundingSourceSelector: "#[payload.params.message.metadata.context]"
      groundingQuerySelector: "#[payload.params.message.parts[0].text]"
      apiTimeoutMs: 8000
      failOpen: false
```

### Fail-Open Configuration with Sampling (High Availability, Cost Control)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: true
    advancedConfiguration:
      failOpen: true # Allow traffic if Bedrock is unavailable
      apiTimeoutMs: 3000
      samplingRatePercent: 50 # Moderate 50% of sessions
```

## Error Responses

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Condition</th><th>Status Code</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Content violates guardrail (request phase)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Request blocked before reaching the agent. Response body contains A2A error envelope with reason details.</p></div></div></td></tr><tr><td><div><div><p>Content violates guardrail (response phase)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Response blocked and replaced with A2A error envelope. Original response is not returned.</p></div></div></td></tr><tr><td><div><div><p>Bedrock API failure (fail-open disabled)</p></div></div></td><td><div><div><p>503 Service Unavailable</p></div></div></td><td><div><div><p>Bedrock service error or timeout with fail-open disabled. Traffic is blocked.</p></div></div></td></tr><tr><td><div><div><p>Bedrock API failure (fail-open enabled)</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Traffic proceeds unmoderated. Observability headers indicate <code>service_unavailable</code>.</p></div></div></td></tr><tr><td><div><div><p>Payload exceeds size limit (fail-open disabled)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Payload larger than <code>maxPayloadBytes</code>. Request blocked.</p></div></div></td></tr><tr><td><div><div><p>Payload exceeds size limit (fail-open enabled)</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Oversized payload passes through unmoderated. Observability headers indicate <code>payload_too_large</code>.</p></div></div></td></tr><tr><td><div><div><p>Sampled-out session</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Session not selected for moderation. Traffic passes through with <code>sampled_out</code> reason header.</p></div></div></td></tr><tr><td><div><div><p>gRPC traffic</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>gRPC traffic passes through unmoderated with <code>unsupported_transport_v1</code> reason header.</p></div></div></td></tr></tbody></table>

## Limitations

- **Streaming responses**: Streaming responses (`text/event-stream`) aren’t moderated and pass
  through unchanged.

- **gRPC traffic**: gRPC traffic isn’t moderated and passes through with observability headers.

- **Payload size**: Payloads exceeding `maxPayloadBytes` (default 25,000 bytes) can’t be evaluated
  synchronously by Bedrock.

- **JSON envelope**: Bedrock evaluates the complete JSON payload, including A2A protocol fields, not
  just the natural language content. This may affect classifier confidence scores compared to
  evaluating bare text.

## Best Practices

1.  **Use versioned guardrails in production**: Pin to a numeric guardrail version instead of
    `DRAFT` for consistent, repeatable behavior.

2.  **Monitor observability headers**: Track `x-flex-bedrock-guardrails-reason` headers to
    understand why content is blocked or skipped.

3.  **Start with sampling in production**: Use `samplingRatePercent: 50` or lower initially to
    control costs while establishing baseline behavior.

4.  **Enable fail-open for availability**: Consider `failOpen: true` in production to prevent
    Bedrock outages from blocking all agent traffic.

5.  **Test grounding with representative payloads**: If using contextual grounding, validate with
    full A2A JSON payloads, not just extracted text fields.

6.  **Use temporary credentials**: Rotate temporary STS credentials instead of long-lived IAM keys
    for improved security.

## See Also

- [Amazon Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) - AWS documentation

- [ApplyGuardrail API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html) -
  AWS API documentation

- [Amazon Bedrock Guardrails Policy](https://docs.mulesoft.com/gateway/latest/policies-included-bedrock-guardrails) - LLM Gateway version

- [A2A v1 PII Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-pii-detector) - Alternative PII detection
  for A2A v1.0

- [Agent Policies](https://docs.mulesoft.com/gateway/latest/agent-policies) - Overview of Omni Gateway agent policies and routing

<!-- document id=c8620e8de427bf363d8228ee19df6503d6e5035c93165a54c95aeb67b1c5ed44 url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-pii-detector.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Personally Identifiable Information (PII) Detector Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 PII Detector</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in A2A v1 requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-pii-detector-release-notes">A2A v1 Personally Identifiable Information (PII) Detector Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403: Forbidden: PII detected and action is set to Reject</p></td></tr></tbody></table>

## Summary

The A2A v1 PII Detector policy detects personally identifiable information (PII) in A2A v1.0 agent
requests across all three transport protocols: JSON-RPC, HTTP+JSON, and gRPC. This policy scans the
message content of `SendMessage` and `SendStreamingMessage` requests for configured PII patterns and
can either reject the request, log the detection, or log and mask the sensitive data.

The policy scans only the text parts of message content (`Part::Text` entries in `message.parts[]`).
File references (`Part::File`) and structured data (`Part::Data`) are not scanned. Read-only methods
like `GetTask`, `ListTasks`, and agent card requests pass through without inspection.

When PII is detected and the action is set to `Reject`, the policy returns an appropriate error
response in the request’s transport protocol format. A policy violation is always reported when PII
is detected, regardless of the configured action.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. For pre-v1.0 A2A traffic, use the
> [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-pii-detector).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 PII Detector policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>PII Types</p></div></div></td><td><div><div><p>Array that defines the types of PII to detect. You can select multiple PII types. Supported values are <code>Email</code>, <code>US SSN</code>, <code>Credit Card</code>, <code>Phone Number</code>.<br>For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Custom PII Patterns</p></div></div></td><td><div><div><p>Optional array of custom regex patterns for detecting additional PII types beyond the built-in ones. Each pattern requires a <code>name</code> and a <code>pattern</code> (regular expression).<br>For more information, see <a href="#custom-patterns">Custom PII Patterns</a>.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Empty array</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>Action to take when PII is detected. Supported values are:</p></div><div><ul><li><p><code>Reject</code>: Blocks the request and returns a 403 Forbidden error</p></li><li><p><code>Log</code>: Allows the request to continue but logs the PII detection</p></li><li><p><code>Log and mask</code>: Allows the request to continue, logs the detection, and masks the sensitive data in logs</p></li></ul></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>Log</code></p></div></div></td></tr></tbody></table>

### PII Types

When you configure an A2A v1 PII Detector policy, you can choose which types of PII to detect.

This table describes the types of PII this policy can detect:

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code></p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs) in the standard format: <code>XXX-XX-XXXX</code> where each <code>X</code> is a digit. For example: <code>123-45-6789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers in the form of four groups of four digits, separated by optional spaces or hyphens. Examples: <code>1234-5678-9012-3456</code>, <code>1234 5678 9012 3456</code>, or <code>1234567890123456</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>United States phone numbers in various formats, with or without country code, parentheses, spaces, hyphens, or dots. Examples: <code>123-456-7890</code>, <code>(123) 456-7890</code>, <code>123.456.7890</code>, <code>+1 123 456 7890</code>, or <code>1234567890123456</code>.</p></div></div></td></tr></tbody></table>

### Custom PII Patterns

In addition to the built-in PII types, you can define custom patterns to detect
organization-specific sensitive data. Each custom pattern consists of:

- **Pattern Name**: A descriptive name to identify this PII pattern in detection results

- **Regex Pattern**: A regular expression pattern to match the sensitive data

Custom patterns are evaluated alongside the built-in PII types.

## How This Policy Works

The A2A v1 PII Detector policy scans A2A v1.0 requests for PII across all three transport protocols:
JSON-RPC, HTTP+JSON, and gRPC.

### Request Scanning

The policy scans only these A2A v1.0 methods:

- `SendMessage`

- `SendStreamingMessage`

For each request, the policy inspects `params.message.parts[]` and scans only `Part::Text` entries.
File references (`Part::File`) and structured data (`Part::Data`) are not scanned.

Read-only methods such as `GetTask`, `ListTasks`, and agent card requests pass through without
inspection. Non-A2A traffic also passes through unchanged.

The policy stops scanning at the first PII detection and applies the configured action to the entire
request.

Based on the configured action:

- **Reject**: Blocks the request and returns an error response in the transport’s format. The
  upstream agent never receives the request.

- **Log**: Forwards the request unchanged and logs findings with actual PII values.

- **Log and mask**: Forwards the request unchanged and logs findings with masked values. Masking
  preserves some characters (for example, email domains, last digits of SSNs) while obscuring
  sensitive portions.

> [!NOTE] The **Log** and **Log and mask** actions forward the request with raw PII to the upstream
> agent. Only **Reject** prevents PII from reaching the agent.

### Response Handling

Unlike the pre-v1.0 A2A PII Detector policy, the A2A v1 PII Detector policy does not scan responses.
This policy is request-only by design.

## Response on Reject

When the policy blocks a request (action set to **Reject**), it returns an error response in the
format appropriate for the transport protocol.

### JSON-RPC Transport

HTTP 403 with a JSON-RPC 2.0 error response:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Request contains PII data: US SSN: 123-45-6789",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "Request contains PII data: US SSN: 123-45-6789"
        }
      }
    ]
  }
}
```

The error code `-32600` maps to the A2A v1.0 `FORBIDDEN` reason code.

### HTTP+JSON Transport

HTTP 403 with a Google RPC Status error response:

```json
{
  "error": {
    "code": 403,
    "message": "Request contains PII data: US SSN: 123-45-6789",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "Request contains PII data: US SSN: 123-45-6789"
        }
      }
    ]
  }
}
```

### gRPC Transport

HTTP 200 with gRPC status headers:

grpc-status: 7 grpc-message: Request%20contains%20PII%20data%3A%20US%20SSN%3A%20123-45-6789

The `grpc-status` code `7` corresponds to `PERMISSION_DENIED`. The response body is empty.

## Examples

### Basic Configuration

This example shows a basic configuration that detects US SSNs and credit card numbers, and rejects
requests containing PII:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-pii-detector
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-pii-detector-flex
  config:
    entities:
      - US SSN
      - Credit Card
    action: Reject
```

### Configuration with Custom Patterns

This example shows a configuration that detects email addresses along with a custom pattern for
internal project codes. The policy logs detections and masks the sensitive data:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-pii-detector-custom
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-pii-detector-flex
  config:
    entities:
      - Email
    customPatterns:
      - name: Internal Project Code
        pattern: "PROJ-[A-Z0-9]{6}"
      - name: Employee ID
        pattern: 'EMP-\d{5}'
    action: Log and mask
```

## Logging Examples

This example shows an A2A v1 request containing multiple PII types and the corresponding log output
for different action configurations.

Sample request:

```json
{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789."
        }
      ]
    }
  }
}
```

- Log

- Log and mask

- Reject

When the action is set to **Log**, the policy logs detected PII with the actual values:

```json
[accessLog] Request: `Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789.` has sensitive data: [
  {
    "pii_type": "Email",
    "value": "john.doe@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "value": "(555) 123-4567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "value": "123-45-6789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Log and mask**, the policy logs detected PII with masked values:

```json
[accessLog] Request: `Contact me at ********@example.com or call (***) ***-4567. My SSN is ***-**-6789.` has sensitive data: [
  {
    "pii_type": "Email",
    "masked_value": "********@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "masked_value": "(***) ***-4567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "masked_value": "***-**-6789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Reject**, the policy blocks the request and returns an error response in
the transport’s format. The upstream agent never receives the original request containing PII.

For this JSON-RPC request, the response would be:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Request contains PII data: US SSN: 123-45-6789",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "Request contains PII data: US SSN: 123-45-6789"
        }
      }
    ]
  }
}
```

A policy violation is reported for monitoring purposes.

### Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern in a request:

```json
{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment"
        }
      ]
    }
  }
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy
logs:

```json
[accessLog] Request: `Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment` has sensitive data: [
  {
    "pii_type": "AWS Access Key",
    "value": "AKIAIOSFODNN7EXAMPLE",
    "start": 18,
    "end": 38
  }
]
```

## Edge Cases

The policy passes through these requests without scanning:

- Non-A2A traffic

- A2A methods other than `SendMessage` and `SendStreamingMessage` (such as `GetTask`, `ListTasks`,
  agent card requests)

- Requests with missing or malformed `params`

- Message parts with types other than `Part::Text` (`Part::File` and `Part::Data` are not scanned)

- Empty text parts

If a regex engine error occurs while scanning a text part, the error is logged and that part is
skipped, but remaining parts continue to be scanned.

## Compliance and Data Flow

This table shows where raw PII values appear based on the configured action.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Request Body on Wire</th><th>Access Log</th></tr></thead><tbody><tr><td><p>Reject</p></td><td><p>Blocked (error response; raw PII values may appear in error message)</p></td><td><p>No log emitted on reject</p></td></tr><tr><td><p>Log</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Raw</p></td></tr><tr><td><p>Log and mask</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Masked</p></td></tr></tbody></table>

> [!IMPORTANT] The **Log and mask** action only masks the access log, not the request body. Raw PII
> still flows to the upstream agent when using **Log** or **Log and mask** actions. Only **Reject**
> prevents PII from reaching the agent.

> [!NOTE] The A2A v1 PII Detector policy scans requests only. It does not scan responses. For
> pre-v1.0 A2A traffic that requires both request and response scanning, use the
> [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-pii-detector).

## See Also

- [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-pii-detector) (for pre-v1.0 A2A traffic)

- [MCP PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-pii-detector)

- [LLM PII Detection Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-llm-pii-detection)

<!-- document id=3b0762be75d2fe96e15dd6a6aa86766a4b4b29f4b2f0b1438b943aff81dbda22 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-pii-detector.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Personally Identifiable Information (PII) Detector Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 PII Detector</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in A2A v1 requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-pii-detector-release-notes">A2A v1 Personally Identifiable Information (PII) Detector Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403: Forbidden: PII detected and action is set to Reject</p></td></tr></tbody></table>

## Summary

The A2A v1 PII Detector policy detects personally identifiable information (PII) in A2A v1.0 agent
requests across all three transport protocols: JSON-RPC, HTTP+JSON, and gRPC. This policy scans the
message content of `SendMessage` and `SendStreamingMessage` requests for configured PII patterns and
can either reject the request, log the detection, or log and mask the sensitive data.

The policy scans only the text parts of message content (`Part::Text` entries in `message.parts[]`).
File references (`Part::File`) and structured data (`Part::Data`) are not scanned. Read-only methods
like `GetTask`, `ListTasks`, and agent card requests pass through without inspection.

When PII is detected and the action is set to `Reject`, the policy returns an appropriate error
response in the request’s transport protocol format. A policy violation is always reported when PII
is detected, regardless of the configured action.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. For pre-v1.0 A2A traffic, use the
> [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-pii-detector).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 PII Detector policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>PII Types</p></div></div></td><td><div><div><p>Array that defines the types of PII to detect. You can select multiple PII types. Supported values are <code>Email</code>, <code>US SSN</code>, <code>Credit Card</code>, <code>Phone Number</code>.<br>For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Custom PII Patterns</p></div></div></td><td><div><div><p>Optional array of custom regex patterns for detecting additional PII types beyond the built-in ones. Each pattern requires a <code>name</code> and a <code>pattern</code> (regular expression).<br>For more information, see <a href="#custom-patterns">Custom PII Patterns</a>.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Empty array</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>Action to take when PII is detected. Supported values are:</p></div><div><ul><li><p><code>Reject</code>: Blocks the request and returns a 403 Forbidden error</p></li><li><p><code>Log</code>: Allows the request to continue but logs the PII detection</p></li><li><p><code>Log and mask</code>: Allows the request to continue, logs the detection, and masks the sensitive data in logs</p></li></ul></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>Log</code></p></div></div></td></tr></tbody></table>

### PII Types

When you configure an A2A v1 PII Detector policy, you can choose which types of PII to detect.

This table describes the types of PII this policy can detect:

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code></p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs) in the standard format: <code>XXX-XX-XXXX</code> where each <code>X</code> is a digit. For example: <code>123-45-6789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers in the form of four groups of four digits, separated by optional spaces or hyphens. Examples: <code>1234-5678-9012-3456</code>, <code>1234 5678 9012 3456</code>, or <code>1234567890123456</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>United States phone numbers in various formats, with or without country code, parentheses, spaces, hyphens, or dots. Examples: <code>123-456-7890</code>, <code>(123) 456-7890</code>, <code>123.456.7890</code>, <code>+1 123 456 7890</code>, or <code>1234567890123456</code>.</p></div></div></td></tr></tbody></table>

### Custom PII Patterns

In addition to the built-in PII types, you can define custom patterns to detect
organization-specific sensitive data. Each custom pattern consists of:

- **Pattern Name**: A descriptive name to identify this PII pattern in detection results

- **Regex Pattern**: A regular expression pattern to match the sensitive data

Custom patterns are evaluated alongside the built-in PII types.

## How This Policy Works

The A2A v1 PII Detector policy scans A2A v1.0 requests for PII across all three transport protocols:
JSON-RPC, HTTP+JSON, and gRPC.

### Request Scanning

The policy scans only these A2A v1.0 methods:

- `SendMessage`

- `SendStreamingMessage`

For each request, the policy inspects `params.message.parts[]` and scans only `Part::Text` entries.
File references (`Part::File`) and structured data (`Part::Data`) are not scanned.

Read-only methods such as `GetTask`, `ListTasks`, and agent card requests pass through without
inspection. Non-A2A traffic also passes through unchanged.

The policy stops scanning at the first PII detection and applies the configured action to the entire
request.

Based on the configured action:

- **Reject**: Blocks the request and returns an error response in the transport’s format. The
  upstream agent never receives the request.

- **Log**: Forwards the request unchanged and logs findings with actual PII values.

- **Log and mask**: Forwards the request unchanged and logs findings with masked values. Masking
  preserves some characters (for example, email domains, last digits of SSNs) while obscuring
  sensitive portions.

> [!NOTE] The **Log** and **Log and mask** actions forward the request with raw PII to the upstream
> agent. Only **Reject** prevents PII from reaching the agent.

### Response Handling

Unlike the pre-v1.0 A2A PII Detector policy, the A2A v1 PII Detector policy does not scan responses.
This policy is request-only by design.

## Response on Reject

When the policy blocks a request (action set to **Reject**), it returns an error response in the
format appropriate for the transport protocol.

### JSON-RPC Transport

HTTP 403 with a JSON-RPC 2.0 error response:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Request contains PII data: US SSN: 123-45-6789",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "Request contains PII data: US SSN: 123-45-6789"
        }
      }
    ]
  }
}
```

The error code `-32600` maps to the A2A v1.0 `FORBIDDEN` reason code.

### HTTP+JSON Transport

HTTP 403 with a Google RPC Status error response:

```json
{
  "error": {
    "code": 403,
    "message": "Request contains PII data: US SSN: 123-45-6789",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "Request contains PII data: US SSN: 123-45-6789"
        }
      }
    ]
  }
}
```

### gRPC Transport

HTTP 200 with gRPC status headers:

grpc-status: 7 grpc-message: Request%20contains%20PII%20data%3A%20US%20SSN%3A%20123-45-6789

The `grpc-status` code `7` corresponds to `PERMISSION_DENIED`. The response body is empty.

## Examples

### Basic Configuration

This example shows a basic configuration that detects US SSNs and credit card numbers, and rejects
requests containing PII:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-pii-detector
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-pii-detector-flex
  config:
    entities:
      - US SSN
      - Credit Card
    action: Reject
```

### Configuration with Custom Patterns

This example shows a configuration that detects email addresses along with a custom pattern for
internal project codes. The policy logs detections and masks the sensitive data:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-pii-detector-custom
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-pii-detector-flex
  config:
    entities:
      - Email
    customPatterns:
      - name: Internal Project Code
        pattern: "PROJ-[A-Z0-9]{6}"
      - name: Employee ID
        pattern: 'EMP-\d{5}'
    action: Log and mask
```

## Logging Examples

This example shows an A2A v1 request containing multiple PII types and the corresponding log output
for different action configurations.

Sample request:

```json
{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789."
        }
      ]
    }
  }
}
```

- Log

- Log and mask

- Reject

When the action is set to **Log**, the policy logs detected PII with the actual values:

```json
[accessLog] Request: `Contact me at john.doe@example.com or call (555) 123-4567. My SSN is 123-45-6789.` has sensitive data: [
  {
    "pii_type": "Email",
    "value": "john.doe@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "value": "(555) 123-4567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "value": "123-45-6789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Log and mask**, the policy logs detected PII with masked values:

```json
[accessLog] Request: `Contact me at ********@example.com or call (***) ***-4567. My SSN is ***-**-6789.` has sensitive data: [
  {
    "pii_type": "Email",
    "masked_value": "********@example.com",
    "start": 14,
    "end": 34
  },
  {
    "pii_type": "Phone Number",
    "masked_value": "(***) ***-4567",
    "start": 43,
    "end": 57
  },
  {
    "pii_type": "US SSN",
    "masked_value": "***-**-6789",
    "start": 70,
    "end": 81
  }
]
```

When the action is set to **Reject**, the policy blocks the request and returns an error response in
the transport’s format. The upstream agent never receives the original request containing PII.

For this JSON-RPC request, the response would be:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Request contains PII data: US SSN: 123-45-6789",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "FORBIDDEN",
        "metadata": {
          "detail": "Request contains PII data: US SSN: 123-45-6789"
        }
      }
    ]
  }
}
```

A policy violation is reported for monitoring purposes.

### Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern in a request:

```json
{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment"
        }
      ]
    }
  }
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy
logs:

```json
[accessLog] Request: `Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment` has sensitive data: [
  {
    "pii_type": "AWS Access Key",
    "value": "AKIAIOSFODNN7EXAMPLE",
    "start": 18,
    "end": 38
  }
]
```

## Edge Cases

The policy passes through these requests without scanning:

- Non-A2A traffic

- A2A methods other than `SendMessage` and `SendStreamingMessage` (such as `GetTask`, `ListTasks`,
  agent card requests)

- Requests with missing or malformed `params`

- Message parts with types other than `Part::Text` (`Part::File` and `Part::Data` are not scanned)

- Empty text parts

If a regex engine error occurs while scanning a text part, the error is logged and that part is
skipped, but remaining parts continue to be scanned.

## Compliance and Data Flow

This table shows where raw PII values appear based on the configured action.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Request Body on Wire</th><th>Access Log</th></tr></thead><tbody><tr><td><p>Reject</p></td><td><p>Blocked (error response; raw PII values may appear in error message)</p></td><td><p>No log emitted on reject</p></td></tr><tr><td><p>Log</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Raw</p></td></tr><tr><td><p>Log and mask</p></td><td><p>Forwarded unchanged (raw PII flows upstream)</p></td><td><p>Masked</p></td></tr></tbody></table>

> [!IMPORTANT] The **Log and mask** action only masks the access log, not the request body. Raw PII
> still flows to the upstream agent when using **Log** or **Log and mask** actions. Only **Reject**
> prevents PII from reaching the agent.

> [!NOTE] The A2A v1 PII Detector policy scans requests only. It does not scan responses. For
> pre-v1.0 A2A traffic that requires both request and response scanning, use the
> [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-pii-detector).

## See Also

- [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-pii-detector) (for pre-v1.0 A2A traffic)

- [MCP PII Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-pii-detector)

- [LLM PII Detection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-llm-pii-detection)

<!-- document id=72422ffbd7e8dd9bad6bef068280bb90cbd88f53cd62aae9a6315d345c54c08d url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-prompt-decorator.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Prompt Decorator Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Prompt Decorator</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Decorates A2A v1 prompts with additional context information</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-prompt-decorator-release-notes">A2A v1 Prompt Decorator Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A v1 Prompt Decorator policy injects additional content into agent prompts before they’re sent
to the upstream agent. This policy supports A2A v1.0 `SendMessage` and `SendStreamingMessage`
requests across all transport protocols: JSON-RPC, HTTP+JSON, and gRPC.

You can decorate prompts with either text content or file references. Text decorators add plain text
to the beginning of the message, while file decorators add external resources via URL or inline
base64-encoded content. All decorators support conditional evaluation using DataWeave expressions,
enabling you to control when specific decorations are applied based on request attributes,
authentication context, or message parameters.

The policy injects content to the beginning of the user message’s `parts[]` array before the request
reaches the upstream agent, ensuring the additional context appears before the user’s original
message. The A2A v1 Prompt Decorator policy decorates A2A v1 prompts with additional context
information. You can add text instructions or file references (via URL or base64-encoded content) to
the beginning of messages before they reach the upstream agent. This policy supports A2A v1.0
traffic across all transport protocols: JSON-RPC, HTTP+JSON, and gRPC.

> [!NOTE] This policy supports A2A v1.0 traffic only. For pre-v1.0 A2A traffic, use the
> [A2A Prompt Decorator Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-prompt-decorator).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Prompt Decorator policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Text Decorators</p></div></div></td><td><div><div><p>Array of text decorations to add to prompts. Each decorator can include a text expression and an optional condition.</p></div><div><p>For more information, see <a href="#text-decorators">Text Decorators</a>.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Empty array</p></div></div></td></tr><tr><td><div><div><p>File Decorators</p></div></div></td><td><div><div><p>Array of file-type decorations to add to prompts. Each decorator specifies file content (URL or base64), file type, and optional metadata like filename and MIME type.</p></div><div><p>For more information, see <a href="#file-decorators">File Decorators</a>.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Empty array</p></div></div></td></tr></tbody></table>

### Text Decorators

Text decorators add plain text content to the beginning of the message. Each text decorator has the
following properties:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Property</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Prompt Text</p></div></div></td><td><div><div><p>DataWeave expression that generates the prompt text injected into the request. The result is added as a text part with media type <code>text/plain</code>.</p></div><div><p>The expression can access:</p></div><div><ul><li><p><code>attributes</code>: Request attributes (headers, query parameters, etc.)</p></li><li><p><code>authentication</code>: Authentication context from upstream authentication policies</p></li><li><p><code>vars.params</code>: The <code>SendMessageParams</code> object containing the message and conversation ID</p></li></ul></div><div><p>For example: <code>#['Use imperial metric units']</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>Optional DataWeave expression that filters which prompts to decorate. If the expression evaluates to <code>true</code>, the decorator is applied; otherwise, it is skipped.</p></div><div><p>For example: <code>#[attributes.headers['x-environment']=='production']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Always applied</p></div></div></td></tr></tbody></table>

### File Decorators

File decorators add file references or inline file content to the beginning of the message. Each
file decorator has the following properties:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Property</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Content</p></div></div></td><td><div><div><p>DataWeave expression containing either a URL to an external file (when <strong>File Source</strong> is <code>Uri</code>) or base64-encoded file content (when <strong>File Source</strong> is <code>Base64</code>).</p></div><div><p>The expression can access <code>attributes</code>, <code>authentication</code>, and <code>vars.params</code>.</p></div><div><p>Base64 content is validated against the pattern <code>^[A-Za-z0-9+/]*={0,2}$</code>. Invalid content causes the decorator to be skipped with a warning logged.</p></div><div><p>For example, URI: <code>#['https://example.com/schema.json']</code></p></div><div><p>For example, Base64: <code>#['QmFzZTY0IGVuY29kZWQgZmlsZSBjb250ZW50']</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>File Source</p></div></div></td><td><div><div><p>Specifies whether the Content field contains a URL or base64-encoded data. Supported values:</p></div><div><ul><li><p><code>Uri</code>: Content is a URL to an external file</p></li><li><p><code>Base64</code>: Content is base64-encoded file data</p></li></ul></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p><code>Base64</code></p></div></div></td></tr><tr><td><div><div><p>File Name</p></div></div></td><td><div><div><p>Optional DataWeave expression that generates the filename for the injected file part.</p></div><div><p>For example: <code>#['api-schema.json']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>File Mime Type</p></div></div></td><td><div><div><p>Optional DataWeave expression that generates the MIME type for the injected file part.</p></div><div><p>If not specified, defaults to <code>application/octet-stream</code>.</p></div><div><p>For example: <code>#['application/json']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>application/octet-stream</code></p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>Optional DataWeave expression that filters which prompts to decorate. If the expression evaluates to <code>true</code>, the decorator is applied; otherwise, it is skipped.</p></div><div><p>For example: <code>#[attributes.headers['x-include-schema']=='true']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Always applied</p></div></div></td></tr></tbody></table>

## Examples

### Text Decoration

This example adds a text instruction to all prompts, directing the agent to use Imperial units:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-text
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    textDecorators:
      - text: "#['Use Imperial metric units for all measurements.']"
```

### Conditional Text Decoration

This example adds different text decorations based on the request environment header:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-conditional
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    textDecorators:
      - text: "#['You are operating in PRODUCTION mode. Be extra careful.']"
        condition: "#[attributes.headers['x-environment']=='production']"
      - text: "#['You are operating in TEST mode. Feel free to experiment.']"
        condition: "#[attributes.headers['x-environment']=='test']"
```

### File Decoration with URI

This example adds an external schema file to all prompts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-file-uri
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    fileDecorators:
      - file: "#['https://example.com/api-schema.json']"
        fileType: Uri
        fileName: "#['api-schema.json']"
        fileMimeType: "#['application/json']"
```

### File Decoration with Base64 Content

This example adds inline base64-encoded content as a file:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-file-base64
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    fileDecorators:
      - file: "#['SGVsbG8sIFdvcmxkIQ==']"
        fileType: Base64
        fileName: "#['greeting.txt']"
        fileMimeType: "#['text/plain']"
```

### Combined Text and File Decorations

The following example combines both text and file decorations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-combined
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    textDecorators:
      - text: "#['Use Imperial metric units.']"
      - text: "#['Follow the API schema provided in the attached file.']"
    fileDecorators:
      - file: "#['https://example.com/schema.json']"
        fileType: Uri
        fileName: "#['api-schema.json']"
        fileMimeType: "#['application/json']"
```

<!-- document id=9bae9c301bca89d5d78d1071de025cf4d20e7b4b8d97cd5cffae80c90e2c8f07 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-prompt-decorator.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Prompt Decorator Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Prompt Decorator</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Decorates A2A v1 prompts with additional context information</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-prompt-decorator-release-notes">A2A v1 Prompt Decorator Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A v1 Prompt Decorator policy injects additional content into agent prompts before they’re sent
to the upstream agent. This policy supports A2A v1.0 `SendMessage` and `SendStreamingMessage`
requests across all transport protocols: JSON-RPC, HTTP+JSON, and gRPC.

You can decorate prompts with either text content or file references. Text decorators add plain text
to the beginning of the message, while file decorators add external resources via URL or inline
base64-encoded content. All decorators support conditional evaluation using DataWeave expressions,
enabling you to control when specific decorations are applied based on request attributes,
authentication context, or message parameters.

The policy injects content to the beginning of the user message’s `parts[]` array before the request
reaches the upstream agent, ensuring the additional context appears before the user’s original
message. The A2A v1 Prompt Decorator policy decorates A2A v1 prompts with additional context
information. You can add text instructions or file references (via URL or base64-encoded content) to
the beginning of messages before they reach the upstream agent. This policy supports A2A v1.0
traffic across all transport protocols: JSON-RPC, HTTP+JSON, and gRPC.

> [!NOTE] This policy supports A2A v1.0 traffic only. For pre-v1.0 A2A traffic, use the
> [A2A Prompt Decorator Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-prompt-decorator).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Prompt Decorator policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Text Decorators</p></div></div></td><td><div><div><p>Array of text decorations to add to prompts. Each decorator can include a text expression and an optional condition.</p></div><div><p>For more information, see <a href="#text-decorators">Text Decorators</a>.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Empty array</p></div></div></td></tr><tr><td><div><div><p>File Decorators</p></div></div></td><td><div><div><p>Array of file-type decorations to add to prompts. Each decorator specifies file content (URL or base64), file type, and optional metadata like filename and MIME type.</p></div><div><p>For more information, see <a href="#file-decorators">File Decorators</a>.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Empty array</p></div></div></td></tr></tbody></table>

### Text Decorators

Text decorators add plain text content to the beginning of the message. Each text decorator has the
following properties:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Property</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Prompt Text</p></div></div></td><td><div><div><p>DataWeave expression that generates the prompt text injected into the request. The result is added as a text part with media type <code>text/plain</code>.</p></div><div><p>The expression can access:</p></div><div><ul><li><p><code>attributes</code>: Request attributes (headers, query parameters, etc.)</p></li><li><p><code>authentication</code>: Authentication context from upstream authentication policies</p></li><li><p><code>vars.params</code>: The <code>SendMessageParams</code> object containing the message and conversation ID</p></li></ul></div><div><p>For example: <code>#['Use imperial metric units']</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>Optional DataWeave expression that filters which prompts to decorate. If the expression evaluates to <code>true</code>, the decorator is applied; otherwise, it is skipped.</p></div><div><p>For example: <code>#[attributes.headers['x-environment']=='production']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Always applied</p></div></div></td></tr></tbody></table>

### File Decorators

File decorators add file references or inline file content to the beginning of the message. Each
file decorator has the following properties:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Property</th><th>Description</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Content</p></div></div></td><td><div><div><p>DataWeave expression containing either a URL to an external file (when <strong>File Source</strong> is <code>Uri</code>) or base64-encoded file content (when <strong>File Source</strong> is <code>Base64</code>).</p></div><div><p>The expression can access <code>attributes</code>, <code>authentication</code>, and <code>vars.params</code>.</p></div><div><p>Base64 content is validated against the pattern <code>^[A-Za-z0-9+/]*={0,2}$</code>. Invalid content causes the decorator to be skipped with a warning logged.</p></div><div><p>For example, URI: <code>#['https://example.com/schema.json']</code></p></div><div><p>For example, Base64: <code>#['QmFzZTY0IGVuY29kZWQgZmlsZSBjb250ZW50']</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>File Source</p></div></div></td><td><div><div><p>Specifies whether the Content field contains a URL or base64-encoded data. Supported values:</p></div><div><ul><li><p><code>Uri</code>: Content is a URL to an external file</p></li><li><p><code>Base64</code>: Content is base64-encoded file data</p></li></ul></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p><code>Base64</code></p></div></div></td></tr><tr><td><div><div><p>File Name</p></div></div></td><td><div><div><p>Optional DataWeave expression that generates the filename for the injected file part.</p></div><div><p>For example: <code>#['api-schema.json']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>None</p></div></div></td></tr><tr><td><div><div><p>File Mime Type</p></div></div></td><td><div><div><p>Optional DataWeave expression that generates the MIME type for the injected file part.</p></div><div><p>If not specified, defaults to <code>application/octet-stream</code>.</p></div><div><p>For example: <code>#['application/json']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>application/octet-stream</code></p></div></div></td></tr><tr><td><div><div><p>Condition</p></div></div></td><td><div><div><p>Optional DataWeave expression that filters which prompts to decorate. If the expression evaluates to <code>true</code>, the decorator is applied; otherwise, it is skipped.</p></div><div><p>For example: <code>#[attributes.headers['x-include-schema']=='true']</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Always applied</p></div></div></td></tr></tbody></table>

## Examples

### Text Decoration

This example adds a text instruction to all prompts, directing the agent to use Imperial units:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-text
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    textDecorators:
      - text: "#['Use Imperial metric units for all measurements.']"
```

### Conditional Text Decoration

This example adds different text decorations based on the request environment header:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-conditional
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    textDecorators:
      - text: "#['You are operating in PRODUCTION mode. Be extra careful.']"
        condition: "#[attributes.headers['x-environment']=='production']"
      - text: "#['You are operating in TEST mode. Feel free to experiment.']"
        condition: "#[attributes.headers['x-environment']=='test']"
```

### File Decoration with URI

This example adds an external schema file to all prompts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-file-uri
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    fileDecorators:
      - file: "#['https://example.com/api-schema.json']"
        fileType: Uri
        fileName: "#['api-schema.json']"
        fileMimeType: "#['application/json']"
```

### File Decoration with Base64 Content

This example adds inline base64-encoded content as a file:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-file-base64
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    fileDecorators:
      - file: "#['SGVsbG8sIFdvcmxkIQ==']"
        fileType: Base64
        fileName: "#['greeting.txt']"
        fileMimeType: "#['text/plain']"
```

### Combined Text and File Decorations

The following example combines both text and file decorations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-prompt-decorator-combined
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-prompt-decorator-flex
  config:
    textDecorators:
      - text: "#['Use Imperial metric units.']"
      - text: "#['Follow the API schema provided in the attached file.']"
    fileDecorators:
      - file: "#['https://example.com/schema.json']"
        fileType: Uri
        fileName: "#['api-schema.json']"
        fileMimeType: "#['application/json']"
```

<!-- document id=2a8cb74a6157d58af90b400327461a32b2d94ea947fb1fbec43f9ce72041b28f url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-schema-validation.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Verifies that requests to the agent are compliant with the A2A v1.0 specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-schema-validation-release-notes">A2A v1 Schema Validation Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request: Invalid request parameters or malformed JSON</p></td></tr><tr><td><p>404 - Not Found: Unknown or invalid method name</p></td></tr></tbody></table>

## Summary

The A2A v1 Schema Validation policy validates incoming requests against the A2A v1.0 specification
across all three supported transports: JSON-RPC, HTTP+JSON, and gRPC. The policy rejects requests
that don’t comply with the strict structural validation rules defined in the A2A v1.0 specification.
Valid requests flow through unchanged.

The policy performs the following validations:

- **JSON-RPC**: Validates the JSON-RPC 2.0 envelope structure and that method names use the
  PascalCase format specified in A2A v1.0 (for example, `SendMessage`, `GetTask`). Request bodies
  are deserialized against the matching request schema.

- **HTTP+JSON**: Validates that URLs match A2A v1.0 HTTP+JSON routes and that request bodies conform
  to the schema for the matched route.

- **gRPC**: Validates that the protobuf payload decodes successfully against the A2A v1.0 gRPC
  service definition.

When validation fails, the policy returns an error response with the appropriate HTTP status code in
the same transport format as the request.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. If you need to support pre-v1.0 agents,
> use the [A2A Schema Validation](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-schema-validation) policy instead. Do not
> apply both policies to the same agent.

### When to Use This Policy

Apply this policy when:

- You want to enforce strict compliance with the A2A v1.0 specification at the gateway level.

- You need to protect backend agents from malformed or invalid requests.

- You want consistent validation across JSON-RPC, HTTP+JSON, and gRPC transports.

- You need to return validation errors before requests reach backend services.

## Transport-Specific Validation

The policy handles each transport differently:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Transport</th><th>Detection Criteria</th><th>Validation Behavior</th></tr></thead><tbody><tr><td><div><div><p>JSON-RPC</p></div></div></td><td><div><div><p><code>POST</code> request with JSON-RPC 2.0 envelope (<code>{"jsonrpc":"2.0", …​}</code>)</p></div></div></td><td><div><div><p>Validates PascalCase method names (A2A v1.0 §9.1) when tagged with <code>a2a-version: 1.0</code>.<br><br>v0.3 path-style method names are rejected with error code <code>-32601</code> (Method not found).<br><br>Request body is deserialized against the matching request schema with strict validation.</p></div></div></td></tr><tr><td><div><div><p>HTTP+JSON</p></div></div></td><td><div><div><p>URL matches an A2A v1.0 HTTP+JSON route</p></div></div></td><td><div><div><p>Performs route lookup and validates the request body schema.<br><br>Path-bound parameters (like <code>id</code> in <code>:cancel</code> or <code>:subscribe</code> routes) are validated.<br><br>Requests tagged as v1 that don’t match a known route are rejected with HTTP 404.</p></div></div></td></tr><tr><td><div><div><p>gRPC</p></div></div></td><td><div><div><p><code>content-type: application/grpc</code> with path <code>/a2a.A2AService/&lt;RPC&gt;</code></p></div></div></td><td><div><div><p>Decodes the protobuf payload against the A2A v1.0 gRPC service definition.<br><br>Successful decode confirms schema compliance.</p></div></div></td></tr><tr><td><div><div><p>Other traffic</p></div></div></td><td><div><div><p>Doesn’t match any A2A transport pattern</p></div></div></td><td><div><div><p>Passes through without validation.</p></div></div></td></tr></tbody></table>

## Error Responses

When validation fails, the policy returns errors in the request’s transport format:

- **JSON-RPC InvalidParams** (HTTP 400): Returns error code `-32602` with `ErrorInfo` details

- **JSON-RPC ParseError** (HTTP 400): Returns error code `-32700` when JSON decode fails

- **JSON-RPC MethodNotFound** (HTTP 404): Returns error code `-32601` for unknown or invalid method
  names

- **HTTP+JSON errors**: Returns the same error structure wrapped in a `google.rpc.Status` envelope
  (A2A v1.0 §11.5)

- **gRPC errors**: Returns HTTP 200 with `grpc-status` header (`3` for INVALID\_ARGUMENT, `12` for
  UNIMPLEMENTED) and `grpc-message` header with error details

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Schema Validation policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

This policy has no configurable parameters.

## Example Validation Errors

### Invalid JSON-RPC Method Name

Request with v0.3-style path method name:

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "/send-message",
  "params": {...}
}
```

Response (HTTP 404):

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "METHOD_NOT_FOUND",
        "metadata": {
          "detail": "Invalid methods: `/send-message`. Valid Methods: SendMessage, GetTask, ..."
        }
      }
    ]
  }
}
```

### Invalid Request Parameters

Request with missing required field:

```json
{
  "jsonrpc": "2.0",
  "id": "456",
  "method": "SendMessage",
  "params": {
    "message": {}
  }
}
```

Response (HTTP 400):

```json
{
  "jsonrpc": "2.0",
  "id": "456",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "INVALID_PARAMS",
        "metadata": {
          "detail": "missing field `text`"
        }
      }
    ]
  }
}
```

<!-- document id=0ff11722dd36e63de1309748cbd273c06ca313851f68b216014fc3bfa4a0f92c url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-schema-validation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Verifies that requests to the agent are compliant with the A2A v1.0 specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-schema-validation-release-notes">A2A v1 Schema Validation Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request: Invalid request parameters or malformed JSON</p></td></tr><tr><td><p>404 - Not Found: Unknown or invalid method name</p></td></tr></tbody></table>

## Summary

The A2A v1 Schema Validation policy validates incoming requests against the A2A v1.0 specification
across all three supported transports: JSON-RPC, HTTP+JSON, and gRPC. The policy rejects requests
that don’t comply with the strict structural validation rules defined in the A2A v1.0 specification.
Valid requests flow through unchanged.

The policy performs the following validations:

- **JSON-RPC**: Validates the JSON-RPC 2.0 envelope structure and that method names use the
  PascalCase format specified in A2A v1.0 (for example, `SendMessage`, `GetTask`). Request bodies
  are deserialized against the matching request schema.

- **HTTP+JSON**: Validates that URLs match A2A v1.0 HTTP+JSON routes and that request bodies conform
  to the schema for the matched route.

- **gRPC**: Validates that the protobuf payload decodes successfully against the A2A v1.0 gRPC
  service definition.

When validation fails, the policy returns an error response with the appropriate HTTP status code in
the same transport format as the request.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. If you need to support pre-v1.0 agents,
> use the [A2A Schema Validation](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-schema-validation) policy instead. Do not
> apply both policies to the same agent.

### When to Use This Policy

Apply this policy when:

- You want to enforce strict compliance with the A2A v1.0 specification at the gateway level.

- You need to protect backend agents from malformed or invalid requests.

- You want consistent validation across JSON-RPC, HTTP+JSON, and gRPC transports.

- You need to return validation errors before requests reach backend services.

## Transport-Specific Validation

The policy handles each transport differently:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Transport</th><th>Detection Criteria</th><th>Validation Behavior</th></tr></thead><tbody><tr><td><div><div><p>JSON-RPC</p></div></div></td><td><div><div><p><code>POST</code> request with JSON-RPC 2.0 envelope (<code>{"jsonrpc":"2.0", …​}</code>)</p></div></div></td><td><div><div><p>Validates PascalCase method names (A2A v1.0 §9.1) when tagged with <code>a2a-version: 1.0</code>.<br><br>v0.3 path-style method names are rejected with error code <code>-32601</code> (Method not found).<br><br>Request body is deserialized against the matching request schema with strict validation.</p></div></div></td></tr><tr><td><div><div><p>HTTP+JSON</p></div></div></td><td><div><div><p>URL matches an A2A v1.0 HTTP+JSON route</p></div></div></td><td><div><div><p>Performs route lookup and validates the request body schema.<br><br>Path-bound parameters (like <code>id</code> in <code>:cancel</code> or <code>:subscribe</code> routes) are validated.<br><br>Requests tagged as v1 that don’t match a known route are rejected with HTTP 404.</p></div></div></td></tr><tr><td><div><div><p>gRPC</p></div></div></td><td><div><div><p><code>content-type: application/grpc</code> with path <code>/a2a.A2AService/&lt;RPC&gt;</code></p></div></div></td><td><div><div><p>Decodes the protobuf payload against the A2A v1.0 gRPC service definition.<br><br>Successful decode confirms schema compliance.</p></div></div></td></tr><tr><td><div><div><p>Other traffic</p></div></div></td><td><div><div><p>Doesn’t match any A2A transport pattern</p></div></div></td><td><div><div><p>Passes through without validation.</p></div></div></td></tr></tbody></table>

## Error Responses

When validation fails, the policy returns errors in the request’s transport format:

- **JSON-RPC InvalidParams** (HTTP 400): Returns error code `-32602` with `ErrorInfo` details

- **JSON-RPC ParseError** (HTTP 400): Returns error code `-32700` when JSON decode fails

- **JSON-RPC MethodNotFound** (HTTP 404): Returns error code `-32601` for unknown or invalid method
  names

- **HTTP+JSON errors**: Returns the same error structure wrapped in a `google.rpc.Status` envelope
  (A2A v1.0 §11.5)

- **gRPC errors**: Returns HTTP 200 with `grpc-status` header (`3` for INVALID\_ARGUMENT, `12` for
  UNIMPLEMENTED) and `grpc-message` header with error details

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Schema Validation policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

This policy has no configurable parameters.

## Example Validation Errors

### Invalid JSON-RPC Method Name

Request with v0.3-style path method name:

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "/send-message",
  "params": {...}
}
```

Response (HTTP 404):

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "METHOD_NOT_FOUND",
        "metadata": {
          "detail": "Invalid methods: `/send-message`. Valid Methods: SendMessage, GetTask, ..."
        }
      }
    ]
  }
}
```

### Invalid Request Parameters

Request with missing required field:

```json
{
  "jsonrpc": "2.0",
  "id": "456",
  "method": "SendMessage",
  "params": {
    "message": {}
  }
}
```

Response (HTTP 400):

```json
{
  "jsonrpc": "2.0",
  "id": "456",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "a2a-protocol.org",
        "reason": "INVALID_PARAMS",
        "metadata": {
          "detail": "missing field `text`"
        }
      }
    ]
  }
}
```

<!-- document id=9511170a7c9039ad03bcee316c7a73a73db95747571c5c76a05cbb2c8980a741 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-a2a-v1-to-v03-transcoder.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, a2a, transcoder, outbound
---

# A2A v1 to v0.3 Transcoder Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 to v0.3 Transcoder</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transcodes protocol messages bidirectionally between A2A v1.0 JSON-RPC clients and A2A v0.3 backend servers</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-to-v03-transcoder-release-notes">A2A v1 to v0.3 Transcoder Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>-32601 (UNSUPPORTED_METHOD_FOR_V03), -32003 (PUSH_NOTIFICATION_NOT_SUPPORTED)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A v1 to v0.3 Transcoder policy enables A2A v1.0 JSON-RPC clients, such as Broker v2 and Mule
A2A Connector v2, to communicate with A2A v0.3 backend agents without requiring backend upgrades.
This is an outbound policy. Apply it to the upstream of an A2A v0.3 backend server instance. The
policy transcodes protocol messages bidirectionally, enabling organizations to upgrade their clients
to A2A v1.0 while continuing to use existing v0.3 backends, including third-party agents.

The policy transforms the following elements between v1.0 and v0.3 formats:

- **Method names**: Converts between v1.0 method names (`SendMessage`, `GetTask`, `SubscribeToTask`)
  and v0.3 method names (`message/send`, `tasks/get`, `tasks/resubscribe`)

- **Message part structure**: Converts between v1.0 JSON member names and the v0.3 `kind`
  discriminator (`text`, `file`, `data`)

- **Enumerations**: Transcodes enum values such as `Message.role` from `ROLE_USER` to `user` and
  `TaskState` from `TASK_STATE_SUBMITTED` to `submitted`

- **Error formats**: Converts between the v1.0 `google.rpc.ErrorInfo` array format and the v0.3
  plain string format

- **Agent cards**: Transforms agent card responses from the v0.3 format to the v1.0 format with
  `additionalInterfaces`

- **Server-Sent Events (SSE)**: Transcodes SSE streams for `SendStreamingMessage` and
  `SubscribeToTask` per-event

The policy applies these transformations in both directions: v1.0 to v0.3 for outbound requests and
v0.3 to v1.0 for inbound responses.

### Transformation Limitations

The following A2A v1.0 methods aren’t supported when transcoding to v0.3:

- **ListTasks**: The v0.3 protocol has no JSON-RPC equivalent for this method. Requests are rejected
  with error code `-32601 UNSUPPORTED_METHOD_FOR_V03`.

- **Push notification configuration methods**: All push notification methods
  (`CreateTaskPushNotificationConfig`, `GetTaskPushNotificationConfig`,
  `ListTaskPushNotificationConfigs`, `DeleteTaskPushNotificationConfig`) are rejected with error
  code `-32003 PUSH_NOTIFICATION_NOT_SUPPORTED`.

All other v1.0 methods are supported with full transcoding.

> [!NOTE] This policy supports A2A v1.0 JSON-RPC clients only. The HTTP+JSON REST binding isn’t
> supported.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 to v0.3 Transcoder policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

This policy has no configurable parameters. The method mappings, enum conversions, and limitation
gates are built into the policy and are automatically applied.

## Examples

### Basic Configuration

This example applies the transcoder policy to a v0.3 backend agent and allows v1.0 clients to
communicate with it:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-to-v03-transcoder
spec:
  targetRef:
    kind: ApiInstance
    name: my-v03-a2a-agent
  policyRef:
    name: a2a-v1-to-v03-transcoder
```

### Use Case: Gradual Migration

This policy is useful for organizations performing a gradual migration from A2A v0.3 to v1.0:

1.  Upgrade client applications such as Broker and connectors to A2A v1.0.

2.  Apply this transcoder policy to existing v0.3 backend agents.

3.  Clients can immediately use v1.0 features while backends remain on v0.3.

4.  Upgrade backend agents to v1.0 at your own pace.

5.  Remove the transcoder policy once all backends are upgraded to v1.0.

<!-- document id=9663c7ca274f8593961de8791f856a658cfccaf65731202eb9d09b455da15204 url=/mulesoft/current/en-us/gateway/latest/policies-outbound-a2a-v1-to-v03-transcoder.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, a2a, transcoder, outbound
---

# A2A v1 to v0.3 Transcoder Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 to v0.3 Transcoder</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transcodes protocol messages bidirectionally between A2A v1.0 JSON-RPC clients and A2A v0.3 backend servers</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-to-v03-transcoder-release-notes">A2A v1 to v0.3 Transcoder Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>-32601 (UNSUPPORTED_METHOD_FOR_V03), -32003 (PUSH_NOTIFICATION_NOT_SUPPORTED)</p></td></tr></tbody></table>

> [!NOTE] This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A
> versions, see [A2A Releases](https://github.com/a2aproject/A2A/releases).

## Summary

The A2A v1 to v0.3 Transcoder policy enables A2A v1.0 JSON-RPC clients, such as Broker v2 and Mule
A2A Connector v2, to communicate with A2A v0.3 backend agents without requiring backend upgrades.
This is an outbound policy. Apply it to the upstream of an A2A v0.3 backend server instance. The
policy transcodes protocol messages bidirectionally, enabling organizations to upgrade their clients
to A2A v1.0 while continuing to use existing v0.3 backends, including third-party agents.

The policy transforms the following elements between v1.0 and v0.3 formats:

- **Method names**: Converts between v1.0 method names (`SendMessage`, `GetTask`, `SubscribeToTask`)
  and v0.3 method names (`message/send`, `tasks/get`, `tasks/resubscribe`)

- **Message part structure**: Converts between v1.0 JSON member names and the v0.3 `kind`
  discriminator (`text`, `file`, `data`)

- **Enumerations**: Transcodes enum values such as `Message.role` from `ROLE_USER` to `user` and
  `TaskState` from `TASK_STATE_SUBMITTED` to `submitted`

- **Error formats**: Converts between the v1.0 `google.rpc.ErrorInfo` array format and the v0.3
  plain string format

- **Agent cards**: Transforms agent card responses from the v0.3 format to the v1.0 format with
  `additionalInterfaces`

- **Server-Sent Events (SSE)**: Transcodes SSE streams for `SendStreamingMessage` and
  `SubscribeToTask` per-event

The policy applies these transformations in both directions: v1.0 to v0.3 for outbound requests and
v0.3 to v1.0 for inbound responses.

### Transformation Limitations

The following A2A v1.0 methods aren’t supported when transcoding to v0.3:

- **ListTasks**: The v0.3 protocol has no JSON-RPC equivalent for this method. Requests are rejected
  with error code `-32601 UNSUPPORTED_METHOD_FOR_V03`.

- **Push notification configuration methods**: All push notification methods
  (`CreateTaskPushNotificationConfig`, `GetTaskPushNotificationConfig`,
  `ListTaskPushNotificationConfigs`, `DeleteTaskPushNotificationConfig`) are rejected with error
  code `-32003 PUSH_NOTIFICATION_NOT_SUPPORTED`.

All other v1.0 methods are supported with full transcoding.

> [!NOTE] This policy supports A2A v1.0 JSON-RPC clients only. The HTTP+JSON REST binding isn’t
> supported.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 to v0.3 Transcoder policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

This policy has no configurable parameters. The method mappings, enum conversions, and limitation
gates are built into the policy and are automatically applied.

## Examples

### Basic Configuration

This example applies the transcoder policy to a v0.3 backend agent and allows v1.0 clients to
communicate with it:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-to-v03-transcoder
spec:
  targetRef:
    kind: ApiInstance
    name: my-v03-a2a-agent
  policyRef:
    name: a2a-v1-to-v03-transcoder
```

### Use Case: Gradual Migration

This policy is useful for organizations performing a gradual migration from A2A v0.3 to v1.0:

1.  Upgrade client applications such as Broker and connectors to A2A v1.0.

2.  Apply this transcoder policy to existing v0.3 backend agents.

3.  Clients can immediately use v1.0 features while backends remain on v0.3.

4.  Upgrade backend agents to v1.0 at your own pace.

5.  Remove the transcoder policy once all backends are upgraded to v1.0.

<!-- document id=592f0c9ae1916a9da12b2acbeb416b3217cf5bb5d28670b37e766dae8ca19fcf url=/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits v1 A2A agent usage of upstream resources</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-token-rate-limit-release-notes">A2A v1 Token Based Rate Limit Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

## Summary

The A2A v1 Token Based Rate Limit policy enforces token-based rate limiting on A2A v1.0 agent
requests across all transport protocols: JSON-RPC, HTTP+JSON, and gRPC. This policy counts tokens
using the GPT-4o-mini tokenizer model and enforces a per-key budget over a configurable time window.

The policy counts tokens from both request and response payloads:

- **Request tokens** - Counted from `SendMessage` and `SendStreamingMessage` requests. Only text
  parts (`Part::Text`) and data parts (`Part::Data`) are counted. File parts (`Part::File`) aren’t
  counted since file URLs or base64 content aren’t sent directly to the LLM.

- **Response tokens** - Counted from response content including message parts, status messages,
  artifacts, and Server-Sent Events (SSE) streams. Response tokens are counted toward the same limit
  to ensure a single conversation can’t exceed the limit by sending tiny prompts.

Read-only methods (`GetTask`, `ListTasks`, push notification methods, agent card requests) and
non-A2A traffic pass through without consuming tokens.

When the token limit is exceeded, the policy blocks the request and returns a
`429 - Too Many Requests` error with rate limit headers indicating the limit, remaining tokens, and
reset time.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. For pre-v1.0 A2A traffic, use the
> [A2A Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-token-rate-limit).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed per resolved key within the specified time period. Must be a positive integer of 1 or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit sliding window. Minimum value is 1000 milliseconds (1 second). The limit refills once the window rolls.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. The expression is evaluated once per request before A2A parsing.</p></div><div><p>Common examples:</p></div><div><ul><li><p><code>#[attributes.headers['ClientId']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per authenticated user</p></li><li><p><code>#[attributes.headers['X-Forwarded-For']]</code>: Rate limit per source IP address</p></li></ul></div><div><p>If the expression fails to resolve to a string, the policy returns HTTP 400 (Bad Request).</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Token Based Rate Limit policy uses a sliding-window rate limiting algorithm. Each unique
key (resolved by the **Key Selector** expression) has its own independent token budget and time
window.

When a request arrives:

1.  The policy resolves the **Key Selector** expression to determine the rate limit key

2.  For `SendMessage` and `SendStreamingMessage` requests, the policy parses the A2A v1.0 message
    and counts request tokens

3.  The policy checks if sufficient tokens remain in the limit for this key

4.  If tokens are available, the request proceeds to the backend

5.  Response tokens are counted toward the same limit

6.  If the limit is exhausted, subsequent requests are rejected with HTTP 429 until the window
    resets

### Token Counting

The policy uses the GPT-4o-mini BPE tokenizer model to count tokens. Within `SendMessage` and
`SendStreamingMessage` requests:

<table><colgroup><col> <col></colgroup><thead><tr><th>Part Type</th><th>Token Counting Behavior</th></tr></thead><tbody><tr><td><div><div><p><code>Part::Text</code></p></div></div></td><td><div><div><p>Yes: The <code>text</code> value is tokenized and counted</p></div></div></td></tr><tr><td><div><div><p><code>Part::Data</code></p></div></div></td><td><div><div><p>Yes: The JSON-serialized <code>data</code> payload is tokenized and counted</p></div></div></td></tr><tr><td><div><div><p><code>Part::File</code></p></div></div></td><td><div><div><p>No: File URLs (<code>url</code>) and base64 content (<code>raw</code>) aren’t counted since they aren’t sent directly to the LLM</p></div></div></td></tr></tbody></table>

Response tokens are counted from:

- Direct message parts in responses

- Status message parts

- Artifact parts

- Server-Sent Events (SSE) stream data (billed once per event)

For more information about the tokenizer model, see the
[OpenAI Platform Tokenizer](https://platform.openai.com/tokenizer).

### Response Headers

When a request is processed (whether accepted or rejected), the policy adds the following headers to
the response:

- `x-token-limit`: The maximum number of tokens allowed per window for this key

- `x-token-remaining`: The number of tokens remaining in the current window for this key

- `x-token-reset`: The remaining time in milliseconds until the window resets for this key

## Examples

### Basic Configuration

This example limits each authenticated user to 10,000 tokens per minute:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 10000
    timePeriodInMilliseconds: 60000
    keySelector: "#[attributes.principal]"
```

### Rate Limit by Client ID

This example limits each client to 50,000 tokens per 5 minutes, based on a `ClientId` header:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit-client
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 50000
    timePeriodInMilliseconds: 300000
    keySelector: "#[attributes.headers['ClientId']]"
```

### Rate Limit by IP Address

This example limits each source IP address to 5,000 tokens per 10 seconds:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit-ip
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 5000
    timePeriodInMilliseconds: 10000
    keySelector: "#[attributes.headers['X-Forwarded-For']]"
```

<!-- document id=d63ab5ff4b88abdaf9b96debe3b9f8083026b605fa03a1c1bb3fec562cb498c0 url=/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits v1 A2A agent usage of upstream resources</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-token-rate-limit-release-notes">A2A v1 Token Based Rate Limit Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

## Summary

The A2A v1 Token Based Rate Limit policy enforces token-based rate limiting on A2A v1.0 agent
requests across all transport protocols: JSON-RPC, HTTP+JSON, and gRPC. This policy counts tokens
using the GPT-4o-mini tokenizer model and enforces a per-key budget over a configurable time window.

The policy counts tokens from both request and response payloads:

- **Request tokens** - Counted from `SendMessage` and `SendStreamingMessage` requests. Only text
  parts (`Part::Text`) and data parts (`Part::Data`) are counted. File parts (`Part::File`) aren’t
  counted since file URLs or base64 content aren’t sent directly to the LLM.

- **Response tokens** - Counted from response content including message parts, status messages,
  artifacts, and Server-Sent Events (SSE) streams. Response tokens are counted toward the same limit
  to ensure a single conversation can’t exceed the limit by sending tiny prompts.

Read-only methods (`GetTask`, `ListTasks`, push notification methods, agent card requests) and
non-A2A traffic pass through without consuming tokens.

When the token limit is exceeded, the policy blocks the request and returns a
`429 - Too Many Requests` error with rate limit headers indicating the limit, remaining tokens, and
reset time.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. For pre-v1.0 A2A traffic, use the
> [A2A Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-token-rate-limit).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed per resolved key within the specified time period. Must be a positive integer of 1 or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit sliding window. Minimum value is 1000 milliseconds (1 second). The limit refills once the window rolls.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. The expression is evaluated once per request before A2A parsing.</p></div><div><p>Common examples:</p></div><div><ul><li><p><code>#[attributes.headers['ClientId']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per authenticated user</p></li><li><p><code>#[attributes.headers['X-Forwarded-For']]</code>: Rate limit per source IP address</p></li></ul></div><div><p>If the expression fails to resolve to a string, the policy returns HTTP 400 (Bad Request).</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Token Based Rate Limit policy uses a sliding-window rate limiting algorithm. Each unique
key (resolved by the **Key Selector** expression) has its own independent token budget and time
window.

When a request arrives:

1.  The policy resolves the **Key Selector** expression to determine the rate limit key

2.  For `SendMessage` and `SendStreamingMessage` requests, the policy parses the A2A v1.0 message
    and counts request tokens

3.  The policy checks if sufficient tokens remain in the limit for this key

4.  If tokens are available, the request proceeds to the backend

5.  Response tokens are counted toward the same limit

6.  If the limit is exhausted, subsequent requests are rejected with HTTP 429 until the window
    resets

### Token Counting

The policy uses the GPT-4o-mini BPE tokenizer model to count tokens. Within `SendMessage` and
`SendStreamingMessage` requests:

<table><colgroup><col> <col></colgroup><thead><tr><th>Part Type</th><th>Token Counting Behavior</th></tr></thead><tbody><tr><td><div><div><p><code>Part::Text</code></p></div></div></td><td><div><div><p>Yes: The <code>text</code> value is tokenized and counted</p></div></div></td></tr><tr><td><div><div><p><code>Part::Data</code></p></div></div></td><td><div><div><p>Yes: The JSON-serialized <code>data</code> payload is tokenized and counted</p></div></div></td></tr><tr><td><div><div><p><code>Part::File</code></p></div></div></td><td><div><div><p>No: File URLs (<code>url</code>) and base64 content (<code>raw</code>) aren’t counted since they aren’t sent directly to the LLM</p></div></div></td></tr></tbody></table>

Response tokens are counted from:

- Direct message parts in responses

- Status message parts

- Artifact parts

- Server-Sent Events (SSE) stream data (billed once per event)

For more information about the tokenizer model, see the
[OpenAI Platform Tokenizer](https://platform.openai.com/tokenizer).

### Response Headers

When a request is processed (whether accepted or rejected), the policy adds the following headers to
the response:

- `x-token-limit`: The maximum number of tokens allowed per window for this key

- `x-token-remaining`: The number of tokens remaining in the current window for this key

- `x-token-reset`: The remaining time in milliseconds until the window resets for this key

## Examples

### Basic Configuration

This example limits each authenticated user to 10,000 tokens per minute:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 10000
    timePeriodInMilliseconds: 60000
    keySelector: "#[attributes.principal]"
```

### Rate Limit by Client ID

This example limits each client to 50,000 tokens per 5 minutes, based on a `ClientId` header:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit-client
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 50000
    timePeriodInMilliseconds: 300000
    keySelector: "#[attributes.headers['ClientId']]"
```

### Rate Limit by IP Address

This example limits each source IP address to 5,000 tokens per 10 seconds:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit-ip
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 5000
    timePeriodInMilliseconds: 10000
    keySelector: "#[attributes.headers['X-Forwarded-For']]"
```

<!-- document id=70d63d23bda0c730354b4e1d7265e4d1e0d5f1abcb33386fa78fa88eb9d23a58 url=/mulesoft/current/en-us/gateway/1.9/flex-agent-publish-apis.md -->

---
product: Omni Gateway
version: 1.9
---

# Adding a Flex Gateway Agent or Tool Instance

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Similar to API instances, use **API Manager** to publish MCP and A2A Server instances for Managed
Flex Gateway or Flex Gateway running in Connected Mode.

For more information, see
[Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool).

## See Also

- [Publishing Managed Gateway and Connected Mode APIs](https://docs.mulesoft.com/gateway/1.9/flex-gateway-publish-apis-conn)

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

<!-- document id=71f1ac4a8791ccaf743e614296cc967337323da0c1e88c2787edfceadceb5c3a url=/mulesoft/current/en-us/gateway/1.12/policies-included-agent-connection-telemetry.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, agent, telemetry, agent connection, A2A, MCP
---

# Agent Connection Telemetry Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Agent Connection Telemetry</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Tracks the number of requests made to agent or MCP server instances</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A and MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>1.11.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Agent Connection Telemetry policy tracks the number of requests and what source makes the
request to agent or MCP server instance.

To track the source of the request, the policy uses a DataWeave expression to extract an
identification value from a request header. By default, the policy extracts the `X-AGENT-ID` header.
The `X-AGENT-ID` header contains the Mulesoft instance ID.

To track the requests, the policy uses the `mulesoft_agent_connection_count(source, destination)`
metric. Where `source` is the identification value extracted from the request header and
`destination` is the agent or MCP server instance ID. Use Anypoint Monitoring to view the metric.

If the policy can’t extract the identification header, the policy doesn’t block or track the
request.

> [!NOTE] The Agent Connection Telemetry policy is applied by default to all agent and MCP server
> instances created using Agent Fabric.

## Configure Policy Parameters

### Flex Gateway Local Mode

The Agent Connection Telemetry policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Source Agent ID</p></div></div></td><td><div><div><p>DataWeave expression to extract the source identification value from the request header. By default, the <code>#[attributes.headers['X-AGENT-ID']]</code> expression extracts the Mulesoft instance ID.</p></div></div></td></tr></tbody></table>

<!-- document id=dc64eaf8cef9e6e1d57793f12100dbd1f35ed601a226471dccf8ae84f7918049 url=/mulesoft/current/en-us/gateway/1.13/policies-included-agent-connection-telemetry.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, agent, telemetry, agent connection, A2A, MCP
---

# Agent Connection Telemetry Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Agent Connection Telemetry</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Tracks the number of requests made to agent or MCP server instances</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A and MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/agent-connection-telemetry-release-notes">Agent Connection Telemetry</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Agent Connection Telemetry policy tracks the number of requests and what source makes the
request to agent or MCP server instance.

To track the source of the request, the policy uses a DataWeave expression to extract an
identification value from a request header. By default, the policy extracts the `X-AGENT-ID` header.
The `X-AGENT-ID` header contains the Mulesoft instance ID.

To track the requests, the policy uses the `mulesoft_agent_connection_count(source, destination)`
metric. Where `source` is the identification value extracted from the request header and
`destination` is the agent or MCP server instance ID. Use Anypoint Monitoring to view the metric.

If the policy can’t extract the identification header, the policy doesn’t block or track the
request.

> [!NOTE] The Agent Connection Telemetry policy is applied by default to all agent and MCP server
> instances created using Agent Fabric.

## Configure Policy Parameters

### Omni Gateway Local Mode

The Agent Connection Telemetry policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Source Agent ID</p></div></div></td><td><div><div><p>DataWeave expression to extract the source identification value from the request header. By default, the <code>#[attributes.headers['X-AGENT-ID']]</code> expression extracts the Mulesoft instance ID.</p></div></div></td></tr></tbody></table>

<!-- document id=84ec32d17610489d65b3add437d54c0d135aafa513bbd41902aaf4afd826cac7 url=/mulesoft/current/en-us/gateway/latest/policies-included-agent-connection-telemetry.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, agent, telemetry, agent connection, A2A, MCP
---

# Agent Connection Telemetry Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Agent Connection Telemetry</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Tracks the number of requests made to agent or MCP server instances</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A and MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/agent-connection-telemetry-release-notes">Agent Connection Telemetry</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Agent Connection Telemetry policy tracks the number of requests and what source makes the
request to agent or MCP server instance.

To track the source of the request, the policy uses a DataWeave expression to extract an
identification value from a request header. By default, the policy extracts the `X-AGENT-ID` header.
The `X-AGENT-ID` header contains the Mulesoft instance ID.

To track the requests, the policy uses the `mulesoft_agent_connection_count(source, destination)`
metric. Where `source` is the identification value extracted from the request header and
`destination` is the agent or MCP server instance ID. Use Anypoint Monitoring to view the metric.

If the policy can’t extract the identification header, the policy doesn’t block or track the
request.

> [!NOTE] The Agent Connection Telemetry policy is applied by default to all agent and MCP server
> instances created using Agent Fabric.

## Configure Policy Parameters

### Omni Gateway Local Mode

The Agent Connection Telemetry policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Source Agent ID</p></div></div></td><td><div><div><p>DataWeave expression to extract the source identification value from the request header. By default, the <code>#[attributes.headers['X-AGENT-ID']]</code> expression extracts the Mulesoft instance ID.</p></div></div></td></tr></tbody></table>

<!-- document id=307b958aa29008cf4411fa61621cc4d59d5f142fceda3123210d71a7affa29e3 url=/mulesoft/current/en-us/gateway/1.13/policies-included-bedrock-guardrails.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, llm, bedrock, guardrails, content safety, pii
---

# Amazon Bedrock Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Amazon Bedrock Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates LLM prompts and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/bedrock-guardrails-release-notes">Amazon Bedrock Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates guardrail policies</p></td></tr><tr><td><p>503 - Service Unavailable: Bedrock API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The Amazon Bedrock Guardrails policy provides comprehensive content moderation for LLM-based APIs by
evaluating prompts and responses against Amazon Bedrock guardrails. The policy integrates with AWS
Bedrock’s [Guardrails](https://aws.amazon.com/bedrock/guardrails/) feature to enforce content safety
policies including:

The policy supports all Amazon Bedrock Guardrail features:

- **Content filters**: Detects and blocks harmful content across four categories (hate, insults,
  sexual, violence) with configurable filter strengths (NONE, LOW, MEDIUM, HIGH).

- **Denied topics**: Blocks content related to specific topics you define, for example, financial
  advice, medical diagnosis

- **Word filters**: Blocks profanity and custom words or phrases you specify

- **PII detection**: Detects and optionally redacts personally identifiable information, for
  example, names, addresses, SSNs, credit cards

- **Contextual grounding**: Evaluates whether LLM responses are grounded in provided reference text
  and relevant to the user query (hallucination detection)

The guardrail’s configuration is managed entirely in AWS. The policy enforces whatever rules you’ve
configured in the specified guardrail.

The policy operates in two independent phases:

- **Request phase** — Moderates user prompts before they reach the upstream LLM, preventing harmful
  or inappropriate prompts from being processed.

- **Response phase** — Moderates LLM responses before they reach the client, ensuring outputs comply
  with safety policies. Streaming responses (`text/event-stream`) aren’t moderated.

When content violates guardrail policies, the request is rejected with a `403` error code and never
reaches the LLM (request phase) or the client receives a `403` instead of the LLM response (response
phase).

## Before You Begin

Before configuring this policy, you need:

1.  **AWS Account** with access to Amazon Bedrock

2.  **Bedrock Guardrail** created and configured in AWS Console

3.  **IAM Credentials** with permissions to call `bedrock:ApplyGuardrail`

4.  **Guardrail ID** from the AWS Console

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Amazon Bedrock Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Bedrock Runtime Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Amazon Bedrock Runtime endpoint URL. Must match your AWS region, for example: <code>https://bedrock-runtime.us-east-1.amazonaws.com</code>.</p></div></div></td></tr><tr><td><div><div><p>AWS Credentials</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS credentials and region used for signing requests to the Bedrock API. See <a href="#aws-credentials">AWS Credentials</a>.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Identifier</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The unique ID of the Bedrock guardrail to apply (for example, <code>paccgfhgnj1dc</code>).</p></div></div></td></tr><tr><td><div><div><p>Guardrail Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Version of the guardrail to apply.</p></div><div><ul><li><p><code>DRAFT</code> (default): Use the working draft version for development and testing</p></li><li><p>Numeric version (for example, <code>"1"</code>, <code>"2"</code>): Use a published version for production deployments</p></li></ul></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the user prompt against the guardrail before forwarding to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the LLM response against the guardrail before returning to the client. Rejected responses return <code>403</code> error code.</p></div><div><p><strong>Note:</strong> Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr></tbody></table>

### AWS Credentials

The policy uses AWS Signature V4 to authenticate with the Bedrock API. Both long-lived IAM
credentials and temporary STS credentials are supported.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Access Key ID</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS access key ID. Supports both:</p></div><div><ul><li><p>Long-lived IAM user credentials (starting with <code>AKIA</code>)</p></li><li><p>Temporary credentials from STS or SSO (starting with <code>ASIA</code>)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Secret Access Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS secret access key corresponding to the Access Key ID.</p></div></div></td></tr><tr><td><div><div><p>Session Token</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>Required when using temporary credentials (Access Key ID starting with <code>ASIA</code>). Leave empty for long-lived IAM user credentials.</p></div></div></td></tr><tr><td><div><div><p>Region</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS region of the Bedrock Runtime endpoint (for example, <code>us-east-1</code>). This must match the region in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the reference text for contextual grounding from the request body.</p></div><div><p>Required only when contextual grounding is enabled on the AWS guardrail. Must be configured together with Grounding Query Selector.</p></div><div><p>Example: <code>#[payload.messages[0].content]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Grounding Query Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the user query for contextual grounding from the request body.</p></div><div><p>Required only when contextual grounding is enabled on the AWS guardrail. Must be configured together with Grounding Source Selector.</p></div><div><p>Example: <code>#[payload.messages[-1].content]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Timeout in milliseconds for calls to the Bedrock <code>ApplyGuardrail</code> API.</p></div><div><ul><li><p>Default: <code>5000</code></p></li><li><p>Range: <code>1000</code> - <code>30000</code></p></li></ul></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Bedrock API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed unmoderated (fail-open mode)</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The Amazon Bedrock Guardrails policy integrates with AWS Bedrock’s content moderation service to
evaluate LLM prompts and responses against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for requests and responses. The two phases mirror AWS
Bedrock’s INPUT and OUTPUT scopes, enabling you to apply different filter strengths to prompts
versus responses when configuring the guardrail in AWS:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the user prompt from the request.

    2.  The policy sends the prompt to Bedrock’s `ApplyGuardrail` API.

    3.  If the prompt violates any guardrail policies, the policy blocks the request and returns a
        `403` error code to the client.

    4.  If the prompt passes, the policy forwards the original request to the upstream LLM.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the LLM response.

    2.  The policy sends the response to Bedrock’s `ApplyGuardrail` API.

    3.  If the response violates any guardrail policies, the policy returns a `403` error code to
        the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation.

### Contextual Grounding

Contextual grounding helps detect hallucinations by scoring LLM responses on two dimensions:

- **Grounding**: Is the response derived from the provided reference text?

- **Relevance**: Does the response actually answer the user’s question?

To enable contextual grounding:

1.  Enable the contextual grounding feature on your AWS Bedrock guardrail.

2.  Configure both **Grounding Source Selector** and **Grounding Query Selector** in the policy.

The selectors are DataWeave expressions that extract:

- **Grounding source**: The reference text the answer should be based on (often the first message in
  a RAG conversation)

- **Query**: The user’s actual question (often the last message)

Both must be configured together. Configuring only one causes the Bedrock API to return an `400`
error code.

Example Configuration

```yaml
advancedConfiguration:
  groundingSourceSelector: "#[payload.messages[0].content]"
  groundingQuerySelector: "#[payload.messages[-1].content]"
```

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-llm-proxy-bedrock-guardrail-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-bedrock-guardrail-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the prompt or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-bedrock-guardrail-reason</code></p></div></div></td><td><div><div><p><code>content_filter</code>, <code>denied_topic</code>, <code>word_filter</code>, <code>pii</code>, <code>grounding</code>, <code>service_unavailable</code></p></div></div></td><td><div><div><p>Why the content was rejected. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: "${GUARDRAIL_IDENTIFIER}"
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: true
```

### Request-Only Moderation (Block Harmful Prompts)

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: false
```

### With Contextual Grounding (Hallucination Detection)

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      sessionToken: "${AWS_SESSION_TOKEN}" # for temporary credentials
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: DRAFT
    moderateRequest: false
    moderateResponse: true
    advancedConfiguration:
      groundingSourceSelector: "#[payload.messages[0].content]"
      groundingQuerySelector: "#[payload.messages[-1].content]"
      apiTimeoutMs: 8000
      failOpen: false
```

### Fail-Open Configuration (High Availability)

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: true
    advancedConfiguration:
      failOpen: true # Allow traffic if Bedrock is unavailable
      apiTimeoutMs: 3000
```

## See Also

- [Amazon Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) - AWS documentation

- [ApplyGuardrail API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html) -
  AWS API documentation

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies) - Other LLM policies

<!-- document id=baacca918777a26d29d2c84c167b79c32293c36520e27e231a9d6d58d9da978e url=/mulesoft/current/en-us/gateway/latest/policies-included-bedrock-guardrails.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, bedrock, guardrails, content safety, pii
---

# Amazon Bedrock Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Amazon Bedrock Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates LLM prompts and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/bedrock-guardrails-release-notes">Amazon Bedrock Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates guardrail policies</p></td></tr><tr><td><p>503 - Service Unavailable: Bedrock API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The Amazon Bedrock Guardrails policy provides comprehensive content moderation for LLM-based APIs by
evaluating prompts and responses against Amazon Bedrock guardrails. The policy integrates with AWS
Bedrock’s [Guardrails](https://aws.amazon.com/bedrock/guardrails/) feature to enforce content safety
policies including:

The policy supports all Amazon Bedrock Guardrail features:

- **Content filters**: Detects and blocks harmful content across four categories (hate, insults,
  sexual, violence) with configurable filter strengths (NONE, LOW, MEDIUM, HIGH).

- **Denied topics**: Blocks content related to specific topics you define, for example, financial
  advice, medical diagnosis

- **Word filters**: Blocks profanity and custom words or phrases you specify

- **PII detection**: Detects and optionally redacts personally identifiable information, for
  example, names, addresses, SSNs, credit cards

- **Contextual grounding**: Evaluates whether LLM responses are grounded in provided reference text
  and relevant to the user query (hallucination detection)

The guardrail’s configuration is managed entirely in AWS. The policy enforces whatever rules you’ve
configured in the specified guardrail.

The policy operates in two independent phases:

- **Request phase** — Moderates user prompts before they reach the upstream LLM, preventing harmful
  or inappropriate prompts from being processed.

- **Response phase** — Moderates LLM responses before they reach the client, ensuring outputs comply
  with safety policies. Streaming responses (`text/event-stream`) aren’t moderated.

When content violates guardrail policies, the request is rejected with a `403` error code and never
reaches the LLM (request phase) or the client receives a `403` instead of the LLM response (response
phase).

## Before You Begin

Before configuring this policy, you need:

1.  **AWS Account** with access to Amazon Bedrock

2.  **Bedrock Guardrail** created and configured in AWS Console

3.  **IAM Credentials** with permissions to call `bedrock:ApplyGuardrail`

4.  **Guardrail ID** from the AWS Console

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Amazon Bedrock Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Bedrock Runtime Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Amazon Bedrock Runtime endpoint URL. Must match your AWS region, for example: <code>https://bedrock-runtime.us-east-1.amazonaws.com</code>.</p></div></div></td></tr><tr><td><div><div><p>AWS Credentials</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS credentials and region used for signing requests to the Bedrock API. See <a href="#aws-credentials">AWS Credentials</a>.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Identifier</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The unique ID of the Bedrock guardrail to apply (for example, <code>paccgfhgnj1dc</code>).</p></div></div></td></tr><tr><td><div><div><p>Guardrail Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Version of the guardrail to apply.</p></div><div><ul><li><p><code>DRAFT</code> (default): Use the working draft version for development and testing</p></li><li><p>Numeric version (for example, <code>"1"</code>, <code>"2"</code>): Use a published version for production deployments</p></li></ul></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the user prompt against the guardrail before forwarding to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the LLM response against the guardrail before returning to the client. Rejected responses return <code>403</code> error code.</p></div><div><p><strong>Note:</strong> Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr></tbody></table>

### AWS Credentials

The policy uses AWS Signature V4 to authenticate with the Bedrock API. Both long-lived IAM
credentials and temporary STS credentials are supported.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Access Key ID</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS access key ID. Supports both:</p></div><div><ul><li><p>Long-lived IAM user credentials (starting with <code>AKIA</code>)</p></li><li><p>Temporary credentials from STS or SSO (starting with <code>ASIA</code>)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Secret Access Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS secret access key corresponding to the Access Key ID.</p></div></div></td></tr><tr><td><div><div><p>Session Token</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>Required when using temporary credentials (Access Key ID starting with <code>ASIA</code>). Leave empty for long-lived IAM user credentials.</p></div></div></td></tr><tr><td><div><div><p>Region</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS region of the Bedrock Runtime endpoint (for example, <code>us-east-1</code>). This must match the region in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the reference text for contextual grounding from the request body.</p></div><div><p>Required only when contextual grounding is enabled on the AWS guardrail. Must be configured together with Grounding Query Selector.</p></div><div><p>Example: <code>#[payload.messages[0].content]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Grounding Query Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the user query for contextual grounding from the request body.</p></div><div><p>Required only when contextual grounding is enabled on the AWS guardrail. Must be configured together with Grounding Source Selector.</p></div><div><p>Example: <code>#[payload.messages[-1].content]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Timeout in milliseconds for calls to the Bedrock <code>ApplyGuardrail</code> API.</p></div><div><ul><li><p>Default: <code>5000</code></p></li><li><p>Range: <code>1000</code> - <code>30000</code></p></li></ul></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Bedrock API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed unmoderated (fail-open mode)</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The Amazon Bedrock Guardrails policy integrates with AWS Bedrock’s content moderation service to
evaluate LLM prompts and responses against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for requests and responses. The two phases mirror AWS
Bedrock’s INPUT and OUTPUT scopes, enabling you to apply different filter strengths to prompts
versus responses when configuring the guardrail in AWS:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the user prompt from the request.

    2.  The policy sends the prompt to Bedrock’s `ApplyGuardrail` API.

    3.  If the prompt violates any guardrail policies, the policy blocks the request and returns a
        `403` error code to the client.

    4.  If the prompt passes, the policy forwards the original request to the upstream LLM.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the LLM response.

    2.  The policy sends the response to Bedrock’s `ApplyGuardrail` API.

    3.  If the response violates any guardrail policies, the policy returns a `403` error code to
        the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation.

### Contextual Grounding

Contextual grounding helps detect hallucinations by scoring LLM responses on two dimensions:

- **Grounding**: Is the response derived from the provided reference text?

- **Relevance**: Does the response actually answer the user’s question?

To enable contextual grounding:

1.  Enable the contextual grounding feature on your AWS Bedrock guardrail.

2.  Configure both **Grounding Source Selector** and **Grounding Query Selector** in the policy.

The selectors are DataWeave expressions that extract:

- **Grounding source**: The reference text the answer should be based on (often the first message in
  a RAG conversation)

- **Query**: The user’s actual question (often the last message)

Both must be configured together. Configuring only one causes the Bedrock API to return an `400`
error code.

Example Configuration

```yaml
advancedConfiguration:
  groundingSourceSelector: "#[payload.messages[0].content]"
  groundingQuerySelector: "#[payload.messages[-1].content]"
```

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-llm-proxy-bedrock-guardrail-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-bedrock-guardrail-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the prompt or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-bedrock-guardrail-reason</code></p></div></div></td><td><div><div><p><code>content_filter</code>, <code>denied_topic</code>, <code>word_filter</code>, <code>pii</code>, <code>grounding</code>, <code>service_unavailable</code></p></div></div></td><td><div><div><p>Why the content was rejected. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: "${GUARDRAIL_IDENTIFIER}"
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: true
```

### Request-Only Moderation (Block Harmful Prompts)

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: false
```

### With Contextual Grounding (Hallucination Detection)

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      sessionToken: "${AWS_SESSION_TOKEN}" # for temporary credentials
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: DRAFT
    moderateRequest: false
    moderateResponse: true
    advancedConfiguration:
      groundingSourceSelector: "#[payload.messages[0].content]"
      groundingQuerySelector: "#[payload.messages[-1].content]"
      apiTimeoutMs: 8000
      failOpen: false
```

### Fail-Open Configuration (High Availability)

```yaml
- policyRef:
    name: bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: true
    advancedConfiguration:
      failOpen: true # Allow traffic if Bedrock is unavailable
      apiTimeoutMs: 3000
```

## See Also

- [Amazon Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) - AWS documentation

- [ApplyGuardrail API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html) -
  AWS API documentation

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies) - Other LLM policies

<!-- document id=9e3db967668376733092d2dc147e094065138ddcb41a6ff69815d4ead2bcab08 url=/mulesoft/current/en-us/gateway/1.13/policies-included-api-security-identification-header.md -->

---
product: Omni Gateway
version: 1.13
keywords: api security, identification, correlation, api gateway, flex gateway, gateway, policy
---

# API Security-Identification Header Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>API Security-Identification Header</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds API instance identifiers as response headers for external security platform correlation</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/api-security-identification-header-release-notes">API Security-Identification Header</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The API Security-Identification Header policy injects organization and API instance identifiers as
response headers to enable integration with external security platforms such as Akamai.

The policy adds these headers in the response phase:

- `x-ms-correlation-id-1`: Contains the business group ID

- `x-ms-correlation-id-2`: Contains the API instance ID

The policy has no configuration parameters and operates transparently without blocking traffic. If
the required metadata is unavailable, the response continues without the headers but logs a warning
is logged for each missing identifier.

If the backend already returns `x-ms-correlation-id-1` or `x-ms-correlation-id-2` headers, the
policy overwrites these values with the platform metadata values.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The API Security-Identification Header policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

The API Security-Identification Header policy doesn’t have configuration parameters.

## Logging

The policy logs the following information:

- **DEBUG level**: The actual organization ID and API instance ID values injected into the headers
  (for example:
  `api-security-identification-header: org.id=a1b2c3d4-e5f6-7890-abcd-ef1234567890, apiId=19203842`)

- **WARN level**: When an organization ID or API instance ID is missing or empty from platform
  metadata

## Example Response

Given the following platform metadata:

- Organization ID: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

- API instance ID: `19203842`

The policy adds the following response headers:

x-ms-correlation-id-1: a1b2c3d4-e5f6-7890-abcd-ef1234567890 x-ms-correlation-id-2: 19203842

<!-- document id=0335884122c13b046d1a2cd8ac8b07ebef180c4c9ee8e17166e3fe2189684b75 url=/mulesoft/current/en-us/gateway/latest/policies-included-api-security-identification-header.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api security, identification, correlation, api gateway, flex gateway, gateway, policy
---

# API Security-Identification Header Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>API Security-Identification Header</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds API instance identifiers as response headers for external security platform correlation</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/api-security-identification-header-release-notes">API Security-Identification Header</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The API Security-Identification Header policy injects organization and API instance identifiers as
response headers to enable integration with external security platforms such as Akamai.

The policy adds these headers in the response phase:

- `x-ms-correlation-id-1`: Contains the business group ID

- `x-ms-correlation-id-2`: Contains the API instance ID

The policy has no configuration parameters and operates transparently without blocking traffic. If
the required metadata is unavailable, the response continues without the headers but logs a warning
is logged for each missing identifier.

If the backend already returns `x-ms-correlation-id-1` or `x-ms-correlation-id-2` headers, the
policy overwrites these values with the platform metadata values.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The API Security-Identification Header policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

The API Security-Identification Header policy doesn’t have configuration parameters.

## Logging

The policy logs the following information:

- **DEBUG level**: The actual organization ID and API instance ID values injected into the headers
  (for example:
  `api-security-identification-header: org.id=a1b2c3d4-e5f6-7890-abcd-ef1234567890, apiId=19203842`)

- **WARN level**: When an organization ID or API instance ID is missing or empty from platform
  metadata

## Example Response

Given the following platform metadata:

- Organization ID: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

- API instance ID: `19203842`

The policy adds the following response headers:

x-ms-correlation-id-1: a1b2c3d4-e5f6-7890-abcd-ef1234567890 x-ms-correlation-id-2: 19203842

<!-- document id=d5000676b2a8ffbc5f4f53bdc9d0fb4c55ec332dabdf23db12f25a774a2a80fe url=/mulesoft/current/en-us/gateway/1.12/policies-automated-applying.md -->

---
product: Omni Gateway
version: 1.12
---

# Applying Automated Inbound Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Users with **Organization Admin**, **Environment Admin**, or with a role to **Manage Policies** in
the environment can create, edit and delete Automated Policies.

> [!NOTE] Automated policies are only supported in the inbound direction.

## Apply an Automated Policy in Connected Mode

To apply an automated policy:

1.  In API Manager, select **Automated Policies** from the left navigation menu.

2.  Click **Apply new automated policy**.

3.  Select the provided policy that you want to configure as a provided policy.

    You can configure any included policies as an automated policy.

    See the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory) to learn how to configure each
    one of them, or [Custom Policies](https://docs.mulesoft.com/gateway/1.12/policies-custom-overview) to learn how to create one.

    If you are configuring a type of policy that also exists as a provided policy in an API proxy
    affected by your rule of application, you’ll need to solve the conflict before continuing. Refer
    to the [Conflict Management](#conflict-management) section below for more information on how to
    solve them.

4.  Click **Apply**

> [!TIP] It’s recommended to apply an automated policy in a lower environment before applying in a
> production environment and ensure to review that an automated policy doesn’t affect the existing
> API contracts.

### Conflict Management

Since automated policies have priority over API-level policies, when adding an automated policy that
it is already applied as an API-level policy, on an API deployed using the selected runtime range, a
conflict results.

When a conflict is detected, a popup with the list of conflicting APIs displays. A message will be
shown with the first 10 APIs with conflicts and the total amount. You can use this endpoint to
access the list of all APIs:

```CURL
curl -X GET \
https://anypoint.mulesoft.com/xapi/v1/automated-policies/{groupId}/{assetId}/conflicting-apis \
-H 'Authorization: Bearer {token}'
```

To solve conflicts, you can either select the APIs from the list of already configured APIs and
manually disable or remove the conflicting policy or choose to override all conflicting policies for
the already configured APIs. If this last option is chosen the conflicting policies in the APIs will
be disabled. If Automated Policy is removed, the API policy will be re-enabled automatically.

### Deploying New APIs

When managing new APIs, you can see information regarding the status of the automated policies
applied to your environment in the **Policies** tab. No automated policies are shown until the
application is in Active status.  
After the application is deployed, a list of applied automated policies will be listed in the
**Policies** tab of the API.

Users with **View Policies** role for the environment will able to see the list of automated
policies applied.

### Viewing Coverage Status

View the **Coverage status** of an instance to see if an automated policy covers your instance or
why it doesn’t. Typically, instances are not covered due to their runtime type or runtime version.

To view what API instances are covered by an automated policy:

1.  Navigate to **Anypoint Platform** > **API Manager**.

2.  In **API instances** or **Agent and Tool Instances**, click **Automated Policies**.

3.  Click the more options button
    (![Three circles displayed horizontally, representing the More Options menu](/mulesoft/current/en-us/gateway/1.12/_images/more-options-menu.png))
    of the policy whose coverage you want to view, and then click **See covered APIs**.

4.  View the API instance’s coverage status in the **Coverage status** column.

> [!NOTE] To filter by coverage status, click the coverage status dropdown and select a coverage
> status option.

### Auditing Applied Policies

It is possible to audit and get a list of all affected APIs by an automated policy. Reports can be
filtered by runtime version, and by an operation.

To get the list of all automated policies in an environment:

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies?environmentId={envId} \
  -H 'Authorization: Bearer {token}'
```

To get the list of APIs included in the range of automated policy or APIs where the automated policy
is not applied.

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies/{automatedPolicyId}/apis \
-H 'Authorization: Bearer {token}'
```

## Apply an Automated Policy in Local Mode

For information about applying an automated policy for Flex Gateway running in Local Mode, see
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.12/flex-local-secure-api-with-auto-policy).

## See Also

- [Automated Policies](https://docs.mulesoft.com/gateway/1.12/policies-automated-overview)

<!-- document id=6417ff28025a60b58d3b7a8580a93390d1afeba41de5a370c3ce0ea2aefd8d78 url=/mulesoft/current/en-us/gateway/1.13/policies-automated-applying.md -->

---
product: Omni Gateway
version: 1.13
---

# Applying Automated Inbound Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Users with **Organization Admin**, **Environment Admin**, or with a role to **Manage Policies** in
the environment can create, edit and delete Automated Policies.

> [!NOTE] Automated policies are only supported in the inbound direction.

## Apply an Automated Policy in Connected Mode

To apply an automated policy:

1.  In API Manager, select **Automated Policies** from the left navigation menu.

2.  Click **Apply new automated policy**.

3.  Select the provided policy that you want to configure as a provided policy.

    You can configure any included policies as an automated policy.

    See the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory) to learn how to configure each
    one of them, or [Custom Policies](https://docs.mulesoft.com/gateway/1.13/policies-custom-overview) to learn how to create one.

    If you are configuring a type of policy that also exists as a provided policy in an API proxy
    affected by your rule of application, you’ll need to solve the conflict before continuing. Refer
    to the [Conflict Management](#conflict-management) section below for more information on how to
    solve them.

4.  Click **Apply**

> [!TIP] It’s recommended to apply an automated policy in a lower environment before applying in a
> production environment and ensure to review that an automated policy doesn’t affect the existing
> API contracts.

### Conflict Management

Since automated policies have priority over API-level policies, when adding an automated policy that
it is already applied as an API-level policy, on an API deployed using the selected runtime range, a
conflict results.

When a conflict is detected, a popup with the list of conflicting APIs displays. A message will be
shown with the first 10 APIs with conflicts and the total amount. You can use this endpoint to
access the list of all APIs:

```CURL
curl -X GET \
https://anypoint.mulesoft.com/xapi/v1/automated-policies/{groupId}/{assetId}/conflicting-apis \
-H 'Authorization: Bearer {token}'
```

To solve conflicts, you can either select the APIs from the list of already configured APIs and
manually disable or remove the conflicting policy or choose to override all conflicting policies for
the already configured APIs. If this last option is chosen the conflicting policies in the APIs will
be disabled. If Automated Policy is removed, the API policy will be re-enabled automatically.

### Deploying New APIs

When managing new APIs, you can see information regarding the status of the automated policies
applied to your environment in the **Policies** tab. No automated policies are shown until the
application is in Active status.  
After the application is deployed, a list of applied automated policies will be listed in the
**Policies** tab of the API.

Users with **View Policies** role for the environment will able to see the list of automated
policies applied.

### Viewing Coverage Status

View the **Coverage status** of an instance to see if an automated policy covers your instance or
why it doesn’t. Typically, instances are not covered due to their runtime type or runtime version.

To view what API instances are covered by an automated policy:

1.  Navigate to **Anypoint Platform** > **API Manager**.

2.  In **API instances** or **Agent and Tool Instances**, click **Automated Policies**.

3.  Click the more options button
    (![Three circles displayed horizontally, representing the More Options menu](/mulesoft/current/en-us/gateway/1.13/_images/more-options-menu.png))
    of the policy whose coverage you want to view, and then click **See covered APIs**.

4.  View the API instance’s coverage status in the **Coverage status** column.

> [!NOTE] To filter by coverage status, click the coverage status dropdown and select a coverage
> status option.

### Auditing Applied Policies

It is possible to audit and get a list of all affected APIs by an automated policy. Reports can be
filtered by runtime version, and by an operation.

To get the list of all automated policies in an environment:

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies?environmentId={envId} \
  -H 'Authorization: Bearer {token}'
```

To get the list of APIs included in the range of automated policy or APIs where the automated policy
is not applied.

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies/{automatedPolicyId}/apis \
-H 'Authorization: Bearer {token}'
```

## Apply an Automated Policy in Local Mode

For information about applying an automated policy for Omni Gateway running in Local Mode, see
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.13/local-secure-api-with-auto-policy).

## See Also

- [Automated Policies](https://docs.mulesoft.com/gateway/1.13/policies-automated-overview)

<!-- document id=032a7225f8d4db42850b64be800807a94cc65502662c6cc99c607a8ce3b26233 url=/mulesoft/current/en-us/gateway/1.9/policies-automated-applying.md -->

---
product: Omni Gateway
version: 1.9
---

# Applying Automated Inbound Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Users with **Organization Admin**, **Environment Admin**, or with a role to **Manage Policies** in
the environment can create, edit and delete Automated Policies.

> [!NOTE] Automated policies are only supported in the inbound direction.

## Apply an Automated Policy in Connected Mode

To apply an automated policy:

1.  In API Manager, select **Automated Policies** from the left navigation menu.

2.  Click **Apply new automated policy**.

3.  Select the provided policy that you want to configure as a provided policy.

    You can configure any included policies as an automated policy.

    See the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory) to learn how to configure each
    one of them, or [Custom Policies](https://docs.mulesoft.com/gateway/1.9/policies-custom-overview) to learn how to create one.

    If you are configuring a type of policy that also exists as a provided policy in an API proxy
    affected by your rule of application, you’ll need to solve the conflict before continuing. Refer
    to the [Conflict Management](#conflict-management) section below for more information on how to
    solve them.

4.  Click **Apply**

> [!TIP] It’s recommended to apply an automated policy in a lower environment before applying in a
> production environment and ensure to review that an automated policy doesn’t affect the existing
> API contracts.

### Conflict Management

Since automated policies have priority over API-level policies, when adding an automated policy that
it is already applied as an API-level policy, on an API deployed using the selected runtime range, a
conflict results.

When a conflict is detected, a popup with the list of conflicting APIs displays. A message will be
shown with the first 10 APIs with conflicts and the total amount. You can use this endpoint to
access the list of all APIs:

```CURL
curl -X GET \
https://anypoint.mulesoft.com/xapi/v1/automated-policies/{groupId}/{assetId}/conflicting-apis \
-H 'Authorization: Bearer {token}'
```

To solve conflicts, you can either select the APIs from the list of already configured APIs and
manually disable or remove the conflicting policy or choose to override all conflicting policies for
the already configured APIs. If this last option is chosen the conflicting policies in the APIs will
be disabled. If Automated Policy is removed, the API policy will be re-enabled automatically.

### Deploying New APIs

When managing new APIs, you can see information regarding the status of the automated policies
applied to your environment in the **Policies** tab. No automated policies are shown until the
application is in Active status.  
After the application is deployed, a list of applied automated policies will be listed in the
**Policies** tab of the API.

Users with **View Policies** role for the environment will able to see the list of automated
policies applied.

### Viewing Coverage Status

View the **Coverage status** of an API instance to see if an automated policy covers your API
instance or why it doesn’t. Typically, instances are not covered due to their runtime type or
runtime version.

To view what API instances are covered by an automated policy:

1.  Navigate to **Anypoint Platform** > **API Manager**.

2.  In API Administration, click **Automated Policies**.

3.  Click the more options button
    (![Three circles displayed horizontally, representing the More Options menu](/mulesoft/current/en-us/gateway/1.9/_images/more-options-menu.png))
    of the policy whose coverage you want to view, and then click **See covered APIs**.

4.  View the API instance’s coverage status in the **Coverage status** column.

> [!NOTE] To filter by coverage status, click the coverage status dropdown and select a coverage
> status option.

### Auditing Applied Policies

It is possible to audit and get a list of all affected APIs by an automated policy. Reports can be
filtered by runtime version, and by an operation.

To get the list of all automated policies in an environment:

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies?environmentId={envId} \
  -H 'Authorization: Bearer {token}'
```

To get the list of APIs included in the range of automated policy or APIs where the automated policy
is not applied.

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies/{automatedPolicyId}/apis \
-H 'Authorization: Bearer {token}'
```

## Apply an Automated Policy in Local Mode

For information about applying an automated policy for Flex Gateway running in Local Mode, see
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.9/flex-local-secure-api-with-auto-policy).

## See Also

- [Automated Policies](https://docs.mulesoft.com/gateway/1.9/policies-automated-overview)

<!-- document id=558d4d3fc7c423f2c56cf7761dc881818ff2979dbfbd76c1f4415022a0bb67dd url=/mulesoft/current/en-us/gateway/latest/policies-automated-applying.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Applying Automated Inbound Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Users with **Organization Admin**, **Environment Admin**, or with a role to **Manage Policies** in
the environment can create, edit and delete Automated Policies.

> [!NOTE] Automated policies are only supported in the inbound direction.

## Apply an Automated Policy in Connected Mode

To apply an automated policy:

1.  In API Manager, select **Automated Policies** from the left navigation menu.

2.  Click **Apply new automated policy**.

3.  Select the provided policy that you want to configure as a provided policy.

    You can configure any included policies as an automated policy.

    See the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory) to learn how to configure each
    one of them, or [Custom Policies](https://docs.mulesoft.com/gateway/latest/policies-custom-overview) to learn how to create one.

    If you are configuring a type of policy that also exists as a provided policy in an API proxy
    affected by your rule of application, you’ll need to solve the conflict before continuing. Refer
    to the [Conflict Management](#conflict-management) section below for more information on how to
    solve them.

4.  Click **Apply**

> [!TIP] It’s recommended to apply an automated policy in a lower environment before applying in a
> production environment and ensure to review that an automated policy doesn’t affect the existing
> API contracts.

### Conflict Management

Since automated policies have priority over API-level policies, when adding an automated policy that
it is already applied as an API-level policy, on an API deployed using the selected runtime range, a
conflict results.

When a conflict is detected, a popup with the list of conflicting APIs displays. A message will be
shown with the first 10 APIs with conflicts and the total amount. You can use this endpoint to
access the list of all APIs:

```CURL
curl -X GET \
https://anypoint.mulesoft.com/xapi/v1/automated-policies/{groupId}/{assetId}/conflicting-apis \
-H 'Authorization: Bearer {token}'
```

To solve conflicts, you can either select the APIs from the list of already configured APIs and
manually disable or remove the conflicting policy or choose to override all conflicting policies for
the already configured APIs. If this last option is chosen the conflicting policies in the APIs will
be disabled. If Automated Policy is removed, the API policy will be re-enabled automatically.

### Deploying New APIs

When managing new APIs, you can see information regarding the status of the automated policies
applied to your environment in the **Policies** tab. No automated policies are shown until the
application is in Active status.  
After the application is deployed, a list of applied automated policies will be listed in the
**Policies** tab of the API.

Users with **View Policies** role for the environment will able to see the list of automated
policies applied.

### Viewing Coverage Status

View the **Coverage status** of an instance to see if an automated policy covers your instance or
why it doesn’t. Typically, instances are not covered due to their runtime type or runtime version.

To view what API instances are covered by an automated policy:

1.  Navigate to **Anypoint Platform** > **API Manager**.

2.  In **API instances** or **Agent and Tool Instances**, click **Automated Policies**.

3.  Click the more options button
    (![Three circles displayed horizontally, representing the More Options menu](/mulesoft/current/en-us/gateway/latest/_images/more-options-menu.png))
    of the policy whose coverage you want to view, and then click **See covered APIs**.

4.  View the API instance’s coverage status in the **Coverage status** column.

> [!NOTE] To filter by coverage status, click the coverage status dropdown and select a coverage
> status option.

### Auditing Applied Policies

It is possible to audit and get a list of all affected APIs by an automated policy. Reports can be
filtered by runtime version, and by an operation.

To get the list of all automated policies in an environment:

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies?environmentId={envId} \
  -H 'Authorization: Bearer {token}'
```

To get the list of APIs included in the range of automated policy or APIs where the automated policy
is not applied.

```curl
curl -X GET \
https://anypoint.mulesoft.com/apimanager/api/v1/organizations/{organizationId}/automated-policies/{automatedPolicyId}/apis \
-H 'Authorization: Bearer {token}'
```

## Apply an Automated Policy in Local Mode

For information about applying an automated policy for Omni Gateway running in Local Mode, see
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/latest/local-secure-api-with-auto-policy).

## See Also

- [Automated Policies](https://docs.mulesoft.com/gateway/latest/policies-automated-overview)

<!-- document id=158f8e1aa85678143a29a5aca11b8266ffb2cae930ccf303b46b6dd039429c38 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-secure-conn.md -->

---
product: Omni Gateway
version: 1.12
---

# Applying Policies for Managed Flex Gateways and Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Flex Gateway and Flex Gateway running in Connected Mode, you apply inbound and outbound
policies using **API Manager**. To find the policies provided by Flex Gateway, see
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-outbound-directory).

## Apply an Inbound Policy

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance to which
    you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click **\+ Add policy**.

5.  Select the policy to apply.

6.  Configure the required parameters.

    For policy configuration parameters, see
    [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory).

7.  If necessary, configure **Advanced options**.

8.  Click **Apply**.

You can apply a policy to the entire instance by default, or to specific methods and resources
within the API.

## Apply an Outbound Policy

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance to which
    you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click **\+ Add outbound policy**.

6.  Select the **Upstream** to which you want to apply a policy.

7.  If you want to apply the policy to an additional upstream, click **Add upstream** and select the
    additional upstream. Repeat this step for all upstreams to which you want to apply the policy.

8.  Click **Next**.

9.  Select the policy to apply.

10. Configure the required parameters.

    For policy configuration parameters, see
    [Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-outbound-directory).

11. If necessary, configure **Advanced options**.

12. Click **Apply**.

You can apply a policy to the entire upstream by default, or to specific methods and resources of
the upstream.

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

<!-- document id=5a59b176e912e2fb6942aa9782c9ed549a836abaa42657ee5e85ed86498901e6 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-secure-conn.md -->

---
product: Omni Gateway
version: 1.9
---

# Applying Policies for Managed Flex Gateways and Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Flex Gateway and Flex Gateway running in Connected Mode, you apply inbound and outbound
policies using **API Manager**. To find the policies provided by Flex Gateway, see
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-outbound-directory).

## Apply an Inbound Policy

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Administration**, click the name of the API to which you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click **\+ Add policy**.

5.  Select the policy to apply.

6.  Configure the required parameters.

    For policy configuration parameters, see
    [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory).

7.  If necessary, configure **Advanced options**.

8.  Click **Apply**.

You can apply a policy to the entire API by default, or to specific methods and resources within the
API.

## Apply an Outbound Policy

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Administration**, click the name of the API to which you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click **\+ Add outbound policy**.

6.  Select the **Upstream** to which you want to apply a policy.

7.  If you want to apply the policy to an additional upstream, click **Add upstream** and select the
    additional upstream. Repeat this step for all upstreams to which you want to apply the policy.

8.  Click **Next**.

9.  Select the policy to apply.

10. Configure the required parameters.

    For policy configuration parameters, see
    [Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-outbound-directory).

11. If necessary, configure **Advanced options**.

12. Click **Apply**.

You can apply a policy to the entire upstream by default, or to specific methods and resources of
the upstream.

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

<!-- document id=ba65099c2a01eb60a8414f4ab91d1faf7536593c9c2cd496d03bcecf9e166da5 url=/mulesoft/current/en-us/gateway/1.13/gateway-secure-conn.md -->

---
product: Omni Gateway
version: 1.13
---

# Applying Policies for Managed Omni Gateways and Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Omni Gateway and Omni Gateway running in Connected Mode, you apply inbound and outbound
policies using **API Manager**. To find the policies provided by Omni Gateway, see
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-outbound-directory).

## Apply Inbound Policies

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance to which
    you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click **\+ Add policy**.

5.  Select the policy to apply.

6.  Configure the required parameters.

    For policy configuration parameters, see
    [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory).

7.  Click **Advanced options** to configure these optional parameters:

    - **Policy label**: A label to identify the policy, specifically for use cases with multiples of
      the same policy.

    - **Policy version**: The version of the policy definition to use.

    - Application conditions: Apply the policy to all incoming requests or requests that match
      specified conditions:

      - **Methods**: The HTTP methods to apply the policy to.

      - **URI template regex**: A URI template regex of which request paths to apply the policy to.

      - **Host**: The host to apply the policy to.

      - **Headers**: A map of headers names and regex values to apply the policy to.

        > [!NOTE] If necessary, use multiples of the same policy to meet all required conditions.

8.  Click **Apply**.

## Apply Outbound Policies

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance to which
    you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click **\+ Add outbound policy**.

6.  Select the **Upstream** to which you want to apply a policy.

7.  If you want to apply the policy to an additional upstream, click **Add upstream** and select the
    additional upstream. Repeat this step for all upstreams to which you want to apply the policy.

8.  Click **Next**.

9.  Select the policy to apply.

10. Configure the required parameters.

    For policy configuration parameters, see
    [Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-outbound-directory).

11. Click **Advanced options** to configure these optional parameters:

    - Policy label: A label to identify the policy, specifically for use cases with multiples of the
      same policy.

    - **Policy version**: The version of the policy definition to use.

    - Application conditions: Apply the policy to all incoming requests or requests that match
      specified conditions:

      - **Methods**: The HTTP methods to apply the policy to.

      - **Headers**: A map of headers names and regex values to apply the policy to.

        > [!NOTE] If necessary, use multiples of the same policy to meet all required conditions.

12. Click **Apply**.

## Upgrade a Policy Definition

To upgrade a policy in API Manager:

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance with the
    policy to upgrade.

3.  From the side navigation panel, click **Policies**.

4.  Click the more options menu (![1%](/mulesoft/current/en-us/gateway/1.13/_images/more-options-menu.png)) of the policy to upgrade, and
    then click **Edit configuration**.

5.  Select the **latest** version for **Policy version**.

6.  Click **Save**.

    > [!NOTE] You must manually check for implementation version updates only when upgrading the
    > **patch** version of a definition (for example, 1.0.0 to 1.0.1). For **minor** and **major**
    > version upgrades (for example, 1.0.0 to 1.1.0 or 1.0.0 t0 2.0.0), the implementation updates
    > automatically. To upgrade a policy implementation, see
    > [Upgrade a Policy Implementation](#upgrade-policy-implementation).

## Upgrade a Policy Implementation

To upgrade a policy implementation in API Manager:

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance with the
    policy to upgrade.

3.  From the side navigation panel, click **Policies**.

4.  Click the more options menu (![1%](/mulesoft/current/en-us/gateway/1.13/_images/more-options-menu.png)) of the policy to upgrade, and
    then click **Check for implementation updates**.

5.  If implementation updates are available, click **Update all**.

6.  Click **Ok**.

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

<!-- document id=d8b42a98c7922ad578a453252f0d45855aed25a82ee15d6b12e9623a19660702 url=/mulesoft/current/en-us/gateway/latest/gateway-secure-conn.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Applying Policies for Managed Omni Gateways and Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Omni Gateway and Omni Gateway running in Connected Mode, you apply inbound and outbound
policies using **API Manager**. To find the policies provided by Omni Gateway, see
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-outbound-directory).

## Apply Inbound Policies

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance to which
    you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click **\+ Add policy**.

5.  Select the policy to apply.

6.  Configure the required parameters.

    For policy configuration parameters, see
    [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory).

7.  Click **Advanced options** to configure these optional parameters:

    - **Policy label**: A label to identify the policy, specifically for use cases with multiples of
      the same policy.

    - **Policy version**: The version of the policy definition to use.

    - Application conditions: Apply the policy to all incoming requests or requests that match
      specified conditions:

      - **Methods**: The HTTP methods to apply the policy to.

      - **URI template regex**: A URI template regex of which request paths to apply the policy to.

      - **Host**: The host to apply the policy to.

      - **Headers**: A map of headers names and regex values to apply the policy to.

        > [!NOTE] If necessary, use multiples of the same policy to meet all required conditions.

8.  Click **Apply**.

## Apply Outbound Policies

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance to which
    you want to apply a policy.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click **\+ Add outbound policy**.

6.  Select the **Upstream** to which you want to apply a policy.

7.  If you want to apply the policy to an additional upstream, click **Add upstream** and select the
    additional upstream. Repeat this step for all upstreams to which you want to apply the policy.

8.  Click **Next**.

9.  Select the policy to apply.

10. Configure the required parameters.

    For policy configuration parameters, see
    [Outbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-outbound-directory).

11. Click **Advanced options** to configure these optional parameters:

    - Policy label: A label to identify the policy, specifically for use cases with multiples of the
      same policy.

    - **Policy version**: The version of the policy definition to use.

    - Application conditions: Apply the policy to all incoming requests or requests that match
      specified conditions:

      - **Methods**: The HTTP methods to apply the policy to.

      - **Headers**: A map of headers names and regex values to apply the policy to.

        > [!NOTE] If necessary, use multiples of the same policy to meet all required conditions.

12. Click **Apply**.

## Upgrade a Policy Definition

To upgrade a policy in API Manager:

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance with the
    policy to upgrade.

3.  From the side navigation panel, click **Policies**.

4.  Click the more options menu (![1%](/mulesoft/current/en-us/gateway/latest/_images/more-options-menu.png)) of the policy to upgrade, and
    then click **Edit configuration**.

5.  Select the **latest** version for **Policy version**.

6.  Click **Save**.

    > [!NOTE] You must manually check for implementation version updates only when upgrading the
    > **patch** version of a definition (for example, 1.0.0 to 1.0.1). For **minor** and **major**
    > version upgrades (for example, 1.0.0 to 1.1.0 or 1.0.0 t0 2.0.0), the implementation updates
    > automatically. To upgrade a policy implementation, see
    > [Upgrade a Policy Implementation](#upgrade-policy-implementation).

## Upgrade a Policy Implementation

To upgrade a policy implementation in API Manager:

1.  Go to **Anypoint Platform > API Manager**.

2.  From **API Instances** or **Agent and Tool Instances**, click the name of the instance with the
    policy to upgrade.

3.  From the side navigation panel, click **Policies**.

4.  Click the more options menu (![1%](/mulesoft/current/en-us/gateway/latest/_images/more-options-menu.png)) of the policy to upgrade, and
    then click **Check for implementation updates**.

5.  If implementation updates are available, click **Update all**.

6.  Click **Ok**.

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

<!-- document id=5c40e1f70b748477797d6744270510a8ef773d7d40f1f2f7918713667e014f73 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-secure-local.md -->

---
product: Omni Gateway
version: 1.12
---

# Applying Policies in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Flex Gateway running in Local Mode, you apply API policies using
[local declarative configuration files](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide). You specify the
location of these configuration files when you first run Flex Gateway.

See [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run) for more information
about how to start the gateway.

Refer to the following tutorials for examples on applying policies to APIs in Local Mode:

- [Secure an API with Basic Authentication and Rate Limiting](https://docs.mulesoft.com/gateway/1.12/flex-local-secure-api-with-basic-auth-policy)

- [Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.12/flex-local-secure-api-with-auto-policy)

- [Secure an API with a Custom Policy](https://docs.mulesoft.com/gateway/1.12/flex-local-deploy-custom-policy)

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

<!-- document id=380afd0740c9b59e3a16b0471fa596018ed0c7487bf429dc844be31993c83138 url=/mulesoft/current/en-us/gateway/1.13/gateway-secure-local.md -->

---
product: Omni Gateway
version: 1.13
---

# Applying Policies in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Omni Gateway running in Local Mode, you apply API policies using
[local declarative configuration files](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide). You specify the
location of these configuration files when you first run Omni Gateway.

See [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run) for more information about
how to start the gateway.

Refer to the following tutorials for examples on applying policies to APIs in Local Mode:

- [Secure an API with Basic Authentication and Rate Limiting](https://docs.mulesoft.com/gateway/1.13/local-secure-api-with-basic-auth-policy)

- [Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.13/local-secure-api-with-auto-policy)

- [Secure an API with a Custom Policy](https://docs.mulesoft.com/gateway/1.13/local-deploy-custom-policy)

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

<!-- document id=e4b18367d016193b3e4160d15c1d4e3d0140ae820545faf7e1e67e6fc6effb72 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-secure-local.md -->

---
product: Omni Gateway
version: 1.9
---

# Applying Policies in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Flex Gateway running in Local Mode, you apply API policies using
[local declarative configuration files](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide). You specify the
location of these configuration files when you first run Flex Gateway.

See [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run) for more information
about how to start the gateway.

Refer to the following tutorials for examples on applying policies to APIs in Local Mode:

- [Secure an API with Basic Authentication and Rate Limiting](https://docs.mulesoft.com/gateway/1.9/flex-local-secure-api-with-basic-auth-policy)

- [Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.9/flex-local-secure-api-with-auto-policy)

- [Secure an API with a Custom Policy](https://docs.mulesoft.com/gateway/1.9/flex-local-deploy-custom-policy)

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

<!-- document id=03cac7f301bac97c8cde782a7b9298b0548a274c1cb4df67cd8f256ccb8f7010 url=/mulesoft/current/en-us/gateway/latest/gateway-secure-local.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Applying Policies in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Omni Gateway running in Local Mode, you apply API policies using
[local declarative configuration files](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide). You specify the
location of these configuration files when you first run Omni Gateway.

See [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run) for more information about
how to start the gateway.

Refer to the following tutorials for examples on applying policies to APIs in Local Mode:

- [Secure an API with Basic Authentication and Rate Limiting](https://docs.mulesoft.com/gateway/latest/local-secure-api-with-basic-auth-policy)

- [Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/latest/local-secure-api-with-auto-policy)

- [Secure an API with a Custom Policy](https://docs.mulesoft.com/gateway/latest/local-deploy-custom-policy)

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

<!-- document id=56de56f89a11f7359f0ec6d368a59b53d38f3eceac11513ea6a38c61274ba2ca url=/mulesoft/current/en-us/gateway/1.12/policies-automated-overview.md -->

---
product: Omni Gateway
version: 1.12
---

# Automated Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use automated policies to enforce security and logging requirements by applying the same policies to
all APIs running in Flex Gateway. With policy automation, you can quickly design, build, and deploy
secure and consistent APIs.

Automated policies enable you to deploy APIs with confidence because the target environment
automatically enforces critical policies, resulting in reduced errors. An administrator no longer
needs to remember to insert a policy to enforce common standards manually.

You can configure all [included policies](https://docs.mulesoft.com/gateway/1.12/policies-included-directory) and
[custom policies](https://docs.mulesoft.com/gateway/1.12/policies-custom-overview) as automated policies and apply them to the APIs running
in an environment.

> [!NOTE] [Alerts](https://docs.mulesoft.com/gateway/1.12/flex-use-api-alerts) cannot be added to API instances protected by automated
> policies.

## See Also

- [Applying Automated Inbound Policies](https://docs.mulesoft.com/gateway/1.12/policies-automated-applying)

<!-- document id=8b0d2a0af88c8e5099c124c6c2d8dde92a4f8fb097cd12f17e08188e7ae6aa05 url=/mulesoft/current/en-us/gateway/1.13/policies-automated-overview.md -->

---
product: Omni Gateway
version: 1.13
---

# Automated Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use automated policies to enforce security and logging requirements by applying the same policies to
all APIs running in Omni Gateway. With policy automation, you can quickly design, build, and deploy
secure and consistent APIs.

Automated policies enable you to deploy APIs with confidence because the target environment
automatically enforces critical policies, resulting in reduced errors. An administrator no longer
needs to remember to insert a policy to enforce common standards manually.

You can configure all [included policies](https://docs.mulesoft.com/gateway/1.13/policies-included-directory) and
[custom policies](https://docs.mulesoft.com/gateway/1.13/policies-custom-overview) as automated policies and apply them to the APIs running
in an environment.

> [!NOTE] [Alerts](https://docs.mulesoft.com/gateway/1.13/use-api-alerts) cannot be added to API instances protected by automated policies.

## See Also

- [Applying Automated Inbound Policies](https://docs.mulesoft.com/gateway/1.13/policies-automated-applying)

<!-- document id=b5194f30b3ef58e9dd3bd9d3964ce45fd87a47cb3942f4a633244f180fc16257 url=/mulesoft/current/en-us/gateway/1.9/policies-automated-overview.md -->

---
product: Omni Gateway
version: 1.9
---

# Automated Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use automated policies to enforce security and logging requirements by applying the same policies to
all APIs running in Flex Gateway. With policy automation, you can quickly design, build, and deploy
secure and consistent APIs.

Automated policies enable you to deploy APIs with confidence because the target environment
automatically enforces critical policies, resulting in reduced errors. An administrator no longer
needs to remember to insert a policy to enforce common standards manually.

You can configure all [included policies](https://docs.mulesoft.com/gateway/1.9/policies-included-directory) and
[custom policies](https://docs.mulesoft.com/gateway/1.9/policies-custom-overview) as automated policies and apply them to the APIs running
in an environment.

> [!NOTE] [Alerts](https://docs.mulesoft.com/gateway/1.9/flex-use-api-alerts) cannot be added to API instances protected by automated
> policies.

## See Also

- [Applying Automated Inbound Policies](https://docs.mulesoft.com/gateway/1.9/policies-automated-applying)

<!-- document id=5ebf59d1055cee1f26fea536e9cbec8bd8324670b72b2fff0db11b4ee5710027 url=/mulesoft/current/en-us/gateway/latest/policies-automated-overview.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Automated Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use automated policies to enforce security and logging requirements by applying the same policies to
all APIs running in Omni Gateway. With policy automation, you can quickly design, build, and deploy
secure and consistent APIs.

Automated policies enable you to deploy APIs with confidence because the target environment
automatically enforces critical policies, resulting in reduced errors. An administrator no longer
needs to remember to insert a policy to enforce common standards manually.

You can configure all [included policies](https://docs.mulesoft.com/gateway/latest/policies-included-directory) and
[custom policies](https://docs.mulesoft.com/gateway/latest/policies-custom-overview) as automated policies and apply them to the APIs running
in an environment.

> [!NOTE] [Alerts](https://docs.mulesoft.com/gateway/latest/use-api-alerts) cannot be added to API instances protected by automated policies.

## See Also

- [Applying Automated Inbound Policies](https://docs.mulesoft.com/gateway/latest/policies-automated-applying)

<!-- document id=e0354cbb4ae1c9bfb6b85bbaab1b4b6d2311e65c84d971bcbb1e99321e888432 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-jenkins-cli.md -->

---
product: Omni Gateway
version: 1.12
---

# Automating Flex Gateway with a Jenkins Pipeline using Anypoint CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Flex Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run a Flex Gateway and use features of the Anypoint CLI, such
as creating and deploying API instances.

To add additional features from the API Manager CLI, see
[CLI for API Manager](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr).

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] Automating your Flex Gateway with Anypoint CLI shares many similarities with Automating
> your Flex Gateway with the API Manager API. To automate your Flex Gateway using API Manger API
> requests, see
> [Automating Flex Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.12/flex-conn-jenkins-api).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.2`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Flex Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Flex Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Flex Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Install Anypoint CLI 4.x](#install-anypoint-cli-4-x)

4.  [Register and Run](#register-and-run).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager CLI
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions before the `pipeline` block in your Jenkinsfile:

```Jenkinsfile
def parseYamlFile(String file) {
    object = readYaml file: file
    return object
}

def getAPIInstanceID(String file) {
    return readFile(file: file).split(' ').last().replace('\n', '').trim()
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuse some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Flex Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Flex Gateway

    - `<gateway-version>`: Version of Flex Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Flex Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.GATEWAY_NAME || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION)  {
                    error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

## Install Anypoint CLI 4.x

To install Anypoint CLI 4.x to your Docker container, add the install Anypoint CLI 4.x `stage` to
the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Install anypoint-cli-v4') {
    steps {
        script {
            sh """
                docker run --name container-anypoint-cli-v4 -d node:16 \
                sh -c " npm install -g anypoint-cli-v4 ; anypoint-cli-v4 plugins:install anypoint-cli-api-mgr-plugin; \
                while :; do sleep 1; done"
            """
            sh """
                docker exec container-anypoint-cli-v4 \
                sh -c "while ! anypoint-cli-v4 plugins 2> /dev/null | grep -q "anypoint-cli-api-mgr-plugin"; do :; done"
            """
        }
    }
}
```

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
   steps {
       script {
           sh """
               docker run --entrypoint flexctl \
                -v ${pwd()}:/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                register \
                --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --environment=${params.ENV_ID} \
                --connected=true \
                --organization=${params.ORG_ID} \
                --output-directory=/registration \
                ${params.GATEWAY_NAME}
           """

           sh """
               grep "name: registration" registration.yaml
           """
       }
   }
}


stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run --name flex-gw -d \
                -v ${pwd()}:/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION}
            """
        }
    }
}
```

## Create an API Instance

After installing Anypoint CLI 4.x, you can create an API instance and deploy it to your Flex
Gateway.

You can repeat this step to add multiple API instances. For additional API configuration flags, see
the [api-mgr:api:manage command](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr#api-mgr-api-manage).

Add the create API instance `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Create API Instance") {
    steps {
        script {
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:manage ${params.EXCHANGE_ASSET_ID} ${params.EXCHANGE_ASSET_VERSION} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --isFlex --withProxy --deploymentType=hybrid --scheme=http --port=8082 \
                --uri=https://httpbin.org:443 --path=/httpbin > api-response
            """
        }
    }
}
```

> [!NOTE] For example, this stage creates an API instance that listens on port `8082` and `/httpbin`
> path and proxies to `https://httpbin.org/443`.

## Apply a Basic Authentication Policy

After you create an API instance, you can apply policies to the API instance.

This stage applies the [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-simple) as
an example, but you can apply any Connected Mode policy. To find additional policies, see
[Included Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory).

To apply a policy:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange, for example
        `` 68ef9520-24e9-4cf2-b2f5-620025690913` ``

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.2`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The Basic Authentication: Simple
      policy uses parameters `"username"` and `"password"`.

2.  After replacing the sample content, add the apply basic authentication policy `stage` to the
    `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Apply Basic Authentication Policy to API Instance") {
    steps {
        script {
            def apiInstanceId = getAPIInstanceID('api-response')
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:policy:apply ${apiInstanceId} 'http-basic-authentication' \
                --policyVersion='1.3.1' --groupId '68ef9520-24e9-4cf2-b2f5-620025690913' \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                -c '{"username": "user", "password": "test"}'
            """
        }
    }
}
```

> [!NOTE] For example, this stage uses the policy GAV and `"configurationData"` associated with the
> [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-simple).

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            sleep(time:15, unit:"SECONDS")
            def registration_file = parseYamlFile('registration.yaml')
            def apiInstanceId = getAPIInstanceID('api-response')

            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:deploy ${apiInstanceId} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --target=${registration_file.spec.platformConnection.agentId[0]} --gatewayVersion=${params.FLEX_VERSION}
            """
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Validate Deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")

            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }

            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Flex Gateway and Archive the Registration File

Use the following code blocks to archive the registration file and remove the Docker container
running Flex Gateway. Add the `post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
    success {
        script {
            // Archive the build output artifacts.
            archiveArtifacts artifacts: 'registration.yaml'
        }
    }
    always {
        script {
            sh(script: "docker rm -f container-anypoint-cli-v4 flex-gw")
        }
    }
}
```

## See Also

- [Anypoint Platform CLI 4.x Overview](https://docs.mulesoft.com/anypoint-cli/latest/)

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run-app).

- [Manage Flex Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.12/flex-conn-manage-public-api)

<!-- document id=cc24479d2044f9a4914e664525104087608223eb9944c57e8e251f9c1bb7ccc9 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-jenkins-cli.md -->

---
product: Omni Gateway
version: 1.9
---

# Automating Flex Gateway with a Jenkins Pipeline using Anypoint CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Flex Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run a Flex Gateway and use features of the Anypoint CLI, such
as creating and deploying API instances.

To add additional features from the API Manager CLI, see
[CLI for API Manager](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr).

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] Automating your Flex Gateway with Anypoint CLI shares many similarities with Automating
> your Flex Gateway with the API Manager API. To automate your Flex Gateway using API Manger API
> requests, see
> [Automating Flex Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.9/flex-conn-jenkins-api).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.2`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Flex Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Flex Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Flex Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Install Anypoint CLI 4.x](#install-anypoint-cli-4-x)

4.  [Register and Run](#register-and-run).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager CLI
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions before the `pipeline` block in your Jenkinsfile:

```Jenkinsfile
def parseYamlFile(String file) {
    object = readYaml file: file
    return object
}

def getAPIInstanceID(String file) {
    return readFile(file: file).split(' ').last().replace('\n', '').trim()
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuse some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Flex Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Flex Gateway

    - `<gateway-version>`: Version of Flex Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Flex Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.GATEWAY_NAME || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION)  {
                    error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

## Install Anypoint CLI 4.x

To install Anypoint CLI 4.x to your Docker container, add the install Anypoint CLI 4.x `stage` to
the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Install anypoint-cli-v4') {
    steps {
        script {
            sh """
                docker run --name container-anypoint-cli-v4 -d node:16 \
                sh -c " npm install -g anypoint-cli-v4 ; anypoint-cli-v4 plugins:install anypoint-cli-api-mgr-plugin; \
                while :; do sleep 1; done"
            """
            sh """
                docker exec container-anypoint-cli-v4 \
                sh -c "while ! anypoint-cli-v4 plugins 2> /dev/null | grep -q "anypoint-cli-api-mgr-plugin"; do :; done"
            """
        }
    }
}
```

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
   steps {
       script {
           sh """
               docker run --entrypoint flexctl \
                -v ${pwd()}:/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                register \
                --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --environment=${params.ENV_ID} \
                --connected=true \
                --organization=${params.ORG_ID} \
                --output-directory=/registration \
                ${params.GATEWAY_NAME}
           """

           sh """
               grep "name: registration" registration.yaml
           """
       }
   }
}


stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run --name flex-gw -d \
                -v ${pwd()}:/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION}
            """
        }
    }
}
```

## Create an API Instance

After installing Anypoint CLI 4.x, you can create an API instance and deploy it to your Flex
Gateway.

You can repeat this step to add multiple API instances. For additional API configuration flags, see
the [api-mgr:api:manage command](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr#api-mgr-api-manage).

Add the create API instance `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Create API Instance") {
    steps {
        script {
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:manage ${params.EXCHANGE_ASSET_ID} ${params.EXCHANGE_ASSET_VERSION} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --isFlex --withProxy --deploymentType=hybrid --scheme=http --port=8082 \
                --uri=https://httpbin.org:443 --path=/httpbin > api-response
            """
        }
    }
}
```

> [!NOTE] For example, this stage creates an API instance that listens on port `8082` and `/httpbin`
> path and proxies to `https://httpbin.org/443`.

## Apply a Basic Authentication Policy

After you create an API instance, you can apply policies to the API instance.

This stage applies the [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-simple) as
an example, but you can apply any Connected Mode policy. To find additional policies, see
[Included Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory).

To apply a policy:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange, for example
        `` 68ef9520-24e9-4cf2-b2f5-620025690913` ``

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.2`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The Basic Authentication: Simple
      policy uses parameters `"username"` and `"password"`.

2.  After replacing the sample content, add the apply basic authentication policy `stage` to the
    `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Apply Basic Authentication Policy to API Instance") {
    steps {
        script {
            def apiInstanceId = getAPIInstanceID('api-response')
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:policy:apply ${apiInstanceId} 'http-basic-authentication' \
                --policyVersion='1.3.1' --groupId '68ef9520-24e9-4cf2-b2f5-620025690913' \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                -c '{"username": "user", "password": "test"}'
            """
        }
    }
}
```

> [!NOTE] For example, this stage uses the policy GAV and `"configurationData"` associated with the
> [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-simple).

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            sleep(time:15, unit:"SECONDS")
            def registration_file = parseYamlFile('registration.yaml')
            def apiInstanceId = getAPIInstanceID('api-response')

            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:deploy ${apiInstanceId} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --target=${registration_file.spec.platformConnection.agentId[0]} --gatewayVersion=${params.FLEX_VERSION}
            """
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Validate Deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")

            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }

            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Flex Gateway and Archive the Registration File

Use the following code blocks to archive the registration file and remove the Docker container
running Flex Gateway. Add the `post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
    success {
        script {
            // Archive the build output artifacts.
            archiveArtifacts artifacts: 'registration.yaml'
        }
    }
    always {
        script {
            sh(script: "docker rm -f container-anypoint-cli-v4 flex-gw")
        }
    }
}
```

## See Also

- [Anypoint Platform CLI 4.x Overview](https://docs.mulesoft.com/anypoint-cli/latest/)

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run-app).

- [Manage Flex Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.9/flex-conn-manage-public-api)

<!-- document id=119ea1cef7ea817f16f3186fec17c7f16f1a9dbafe7ee2e5c041520cb5608924 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-jenkins-api.md -->

---
product: Omni Gateway
version: 1.12
---

# Automating Flex Gateway with a Jenkins Pipeline using the API Manager API

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Flex Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run a Flex Gateway and use features of the API Manager API,
such as creating and deploying API instances.

Automating your Flex Gateway in Connected Mode work flow shares many similarities with the
[Manage Flex Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.12/flex-conn-manage-public-api) tutorial. You can use
the Jenkins Pipeline to automate the calls made to the API Manager API. To add additional features
from the
[API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/),
use the [Create an API Instance](#create-an-api-instance) and
[Apply an API Policy](#apply-an-api-policy) Pipeline stages as examples.

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] To instead automate your Flex Gateway with the Anypoint CLI, see
> [Automating Flex Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/1.12/flex-conn-jenkins-cli).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Flex Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Flex Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Flex Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Register and Run](#register-and-run).

4.  [Obtain an Authorization Token from Access Management](#obtain-an-authorization-token-from-access-management).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager API
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions in your Jenkinsfile. Define the functions before the
`pipeline` block:

```Jenkinsfile
def parseYamlFile(String file) {
   object = readYaml file: file
   return object
}

def parseJsonFile(file) {
   object = readJSON file: file
   return object
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuses some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Flex Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Flex Gateway

    - `<gateway-version>`: Version of Flex Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`:\*Secret\* of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Flex Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION || !params.GATEWAY_NAME)  {
                error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
    steps {
        script {
            sh """
                docker run --entrypoint flexctl \
                    -v "\$(pwd)":/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                    register \
                    --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                    --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                    --environment=${params.ENV_ID} \
                    --connected=true \
                    --organization=${params.ORG_ID} \
                    --output-directory=/registration \
                    ${params.GATEWAY_NAME}
                """
                if (!fileExists('registration.yaml')) {
                    error("Registration failed")
                }
        }
    }
}

stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run -d \
                -v "\$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION} > containerId
            """
        }
    }
}
```

### Obtain an Authorization Token from Access Management

After registering and running your Flex Gateway, you must obtain a valid authorization token from
Access Management in order to authenticate subsequent requests.

To login in to Anypoint, add the Anypoint login `stage` the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Anypoint login") {
    steps {
        script {
            def cmd = """curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' -o 'login-response' \
                    --header 'Content-Type: application/json' \
                    --data-raw '{"grant_type": "client_credentials", "client_id": "${params.CONNECTED_APP_CLIENT_ID}", "client_secret": "${params.CONNECTED_APP_CLIENT_SECRET}"}'
                    """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Anypoint login failed")
            }
        }
    }
}
```

The authorization token returned in this step is saved for subsequent requests.

## Create an API Instance

Having an authorization token from Access Management enables you to create an API instance and
deploy it to your Flex Gateway.

You can repeat this step to add multiple API instances.

For example, this stage creates an API instance that listens on port `8082` and `/httpbin` path and
proxies to `https://httpbin.org/`.

To create an API instance:

1.  Collect the following information:

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI for you API instance

    - `"isCloudHub"`: Cloud Hub status, for example `null` or `true`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  After replacing the HTTP addresses, add the create API instance `stage` to the `stages` block in
    your Jenkinsfile:

```Jenkinsfile
stage("Create API instance") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def cmd = """
                curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis' -o 'api-response' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                "spec": {
                    "groupId": "${params.ORG_ID}",
                    "assetId": "${params.EXCHANGE_ASSET_ID}",
                    "version": "${params.EXCHANGE_ASSET_VERSION}"
                },
                "endpoint": {
                    "deploymentType": "HY",
                    "uri": "https://httpbin.org:443",
                    "proxyUri": "http://0.0.0.0:8082/httpbin",
                    "isCloudHub": null
                },
                "technology": "flexGateway"
                "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
                }'
            """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to create API instance")
            }
        }
    }
}
```

## Apply an API Policy

After you create an API instance, you can apply Connected Mode policies to the instance:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The `"username"` and `"password"`
      parameters are only an example. To find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory).

2.  After replacing the sample content, add the apply policy `stage` to the `stages` block in your
    Jenkinsfile:

```Jenkinsfile
stage("Apply policy") {
   steps {
       script {
           def login_response = parseJsonFile('login-response')
           def api_response = parseJsonFile('api-response')


           def cmd = """
               curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/policies' \
               --header 'Authorization: Bearer ${login_response.access_token}' \
               --header 'Content-Type: application/json' \
               --data-raw '{
                 "configurationData":{
                    "username": "user",
                    "password": "test"
                 },
                 "pointcutData": null,
                 "assetId": "<policy-asset-id>",
                 "assetVersion": "<policy-asset-id>",
                 "groupId": "<policy-group-id>"
                }'
           """


           def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
           if (status_code > 399) {
               error("Error occurred while trying to apply Basic Auth Policy to the API instance")
           }
       }
   }
}
```

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def api_response = parseJsonFile('api-response')
            def registration_file = parseYamlFile('registration.yaml')


            def cmd = """
                curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/deployments' \
                --header 'Content-Type: application/json' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --data-raw '{
                "type": "HY",
                "gatewayVersion": "${params.FLEX_VERSION}",
                "targetId": "${registration_file.spec.platformConnection.agentId[0]}",
                "environmentId": "${params.ENV_ID}"
                }'
            """


            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to deploy the API instance")
            }
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile

```Jenkinsfile
stage("Validate deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")


            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }


            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Flex Gateway and archive the registration file

Use the following code blocks to stop your Flex Gateway and archive the registration file. Add the
`post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
   success {
       script {
           // Archive the build output artifacts.
           archiveArtifacts artifacts: 'registration.yaml'
       }
   }
   always {
       script {
           if (fileExists('containerId')) {
               sh(script: "docker rm -f ${readFile(file: 'containerId')}")
           }
       }
   }
}
```

## See Also

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run-app).

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

- [Manage Flex Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.12/flex-conn-manage-public-api)

<!-- document id=3d692aa5610cf09a430fe30be4742e2242d26200cd5e9f0544e3b75ba69fd3f1 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-jenkins-api.md -->

---
product: Omni Gateway
version: 1.9
---

# Automating Flex Gateway with a Jenkins Pipeline using the API Manager API

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Flex Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run a Flex Gateway and use features of the API Manager API,
such as creating and deploying API instances.

Automating your Flex Gateway in Connected Mode work flow shares many similarities with the
[Manage Flex Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.9/flex-conn-manage-public-api) tutorial. You can use
the Jenkins Pipeline to automate the calls made to the API Manager API. To add additional features
from the
[API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/),
use the [Create an API Instance](#create-an-api-instance) and
[Apply an API Policy](#apply-an-api-policy) Pipeline stages as examples.

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] To instead automate your Flex Gateway with the Anypoint CLI, see
> [Automating Flex Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/1.9/flex-conn-jenkins-cli).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Flex Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Flex Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Flex Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Register and Run](#register-and-run).

4.  [Obtain an Authorization Token from Access Management](#obtain-an-authorization-token-from-access-management).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager API
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions in your Jenkinsfile. Define the functions before the
`pipeline` block:

```Jenkinsfile
def parseYamlFile(String file) {
   object = readYaml file: file
   return object
}

def parseJsonFile(file) {
   object = readJSON file: file
   return object
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuses some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Flex Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Flex Gateway

    - `<gateway-version>`: Version of Flex Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`:\*Secret\* of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Flex Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION || !params.GATEWAY_NAME)  {
                error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
    steps {
        script {
            sh """
                docker run --entrypoint flexctl \
                    -v "\$(pwd)":/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                    register \
                    --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                    --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                    --environment=${params.ENV_ID} \
                    --connected=true \
                    --organization=${params.ORG_ID} \
                    --output-directory=/registration \
                    ${params.GATEWAY_NAME}
                """
                if (!fileExists('registration.yaml')) {
                    error("Registration failed")
                }
        }
    }
}

stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run -d \
                -v "\$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION} > containerId
            """
        }
    }
}
```

### Obtain an Authorization Token from Access Management

After registering and running your Flex Gateway, you must obtain a valid authorization token from
Access Management in order to authenticate subsequent requests.

To login in to Anypoint, add the Anypoint login `stage` the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Anypoint login") {
    steps {
        script {
            def cmd = """curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' -o 'login-response' \
                    --header 'Content-Type: application/json' \
                    --data-raw '{"grant_type": "client_credentials", "client_id": "${params.CONNECTED_APP_CLIENT_ID}", "client_secret": "${params.CONNECTED_APP_CLIENT_SECRET}"}'
                    """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Anypoint login failed")
            }
        }
    }
}
```

The authorization token returned in this step is saved for subsequent requests.

## Create an API Instance

Having an authorization token from Access Management enables you to create an API instance and
deploy it to your Flex Gateway.

You can repeat this step to add multiple API instances.

For example, this stage creates an API instance that listens on port `8082` and `/httpbin` path and
proxies to `https://httpbin.org/`.

To create an API instance:

1.  Collect the following information:

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI for you API instance

    - `"isCloudHub"`: Cloud Hub status, for example `null` or `true`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  After replacing the HTTP addresses, add the create API instance `stage` to the `stages` block in
    your Jenkinsfile:

```Jenkinsfile
stage("Create API instance") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def cmd = """
                curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis' -o 'api-response' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                "spec": {
                    "groupId": "${params.ORG_ID}",
                    "assetId": "${params.EXCHANGE_ASSET_ID}",
                    "version": "${params.EXCHANGE_ASSET_VERSION}"
                },
                "endpoint": {
                    "deploymentType": "HY",
                    "uri": "https://httpbin.org:443",
                    "proxyUri": "http://0.0.0.0:8082/httpbin",
                    "isCloudHub": null
                },
                "technology": "flexGateway"
                "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
                }'
            """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to create API instance")
            }
        }
    }
}
```

## Apply an API Policy

After you create an API instance, you can apply Connected Mode policies to the instance:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The `"username"` and `"password"`
      parameters are only an example. To find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory).

2.  After replacing the sample content, add the apply policy `stage` to the `stages` block in your
    Jenkinsfile:

```Jenkinsfile
stage("Apply policy") {
   steps {
       script {
           def login_response = parseJsonFile('login-response')
           def api_response = parseJsonFile('api-response')


           def cmd = """
               curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/policies' \
               --header 'Authorization: Bearer ${login_response.access_token}' \
               --header 'Content-Type: application/json' \
               --data-raw '{
                 "configurationData":{
                    "username": "user",
                    "password": "test"
                 },
                 "pointcutData": null,
                 "assetId": "<policy-asset-id>",
                 "assetVersion": "<policy-asset-id>",
                 "groupId": "<policy-group-id>"
                }'
           """


           def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
           if (status_code > 399) {
               error("Error occurred while trying to apply Basic Auth Policy to the API instance")
           }
       }
   }
}
```

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def api_response = parseJsonFile('api-response')
            def registration_file = parseYamlFile('registration.yaml')


            def cmd = """
                curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/deployments' \
                --header 'Content-Type: application/json' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --data-raw '{
                "type": "HY",
                "gatewayVersion": "${params.FLEX_VERSION}",
                "targetId": "${registration_file.spec.platformConnection.agentId[0]}",
                "environmentId": "${params.ENV_ID}"
                }'
            """


            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to deploy the API instance")
            }
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile

```Jenkinsfile
stage("Validate deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")


            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }


            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Flex Gateway and archive the registration file

Use the following code blocks to stop your Flex Gateway and archive the registration file. Add the
`post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
   success {
       script {
           // Archive the build output artifacts.
           archiveArtifacts artifacts: 'registration.yaml'
       }
   }
   always {
       script {
           if (fileExists('containerId')) {
               sh(script: "docker rm -f ${readFile(file: 'containerId')}")
           }
       }
   }
}
```

## See Also

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run-app).

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

- [Manage Flex Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.9/flex-conn-manage-public-api)

<!-- document id=e87a58dd2f5e7bb505c8752710239f6197c58f7296d1145e8b0ca40daa0f7660 url=/mulesoft/current/en-us/gateway/1.13/conn-jenkins-cli.md -->

---
product: Omni Gateway
version: 1.13
---

# Automating Omni Gateway with a Jenkins Pipeline using Anypoint CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Omni Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run an Omni Gateway and use features of the Anypoint CLI,
such as creating and deploying API instances.

To add additional features from the API Manager CLI, see
[CLI for API Manager](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr).

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] Automating your Omni Gateway with Anypoint CLI shares many similarities with Automating
> your Omni Gateway with the API Manager API. To automate your Omni Gateway using API Manger API
> requests, see
> [Automating Omni Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.13/conn-jenkins-api).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.2`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Omni Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Omni Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Omni Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Install Anypoint CLI 4.x](#install-anypoint-cli-4-x)

4.  [Register and Run](#register-and-run).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager CLI
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions before the `pipeline` block in your Jenkinsfile:

```Jenkinsfile
def parseYamlFile(String file) {
    object = readYaml file: file
    return object
}

def getAPIInstanceID(String file) {
    return readFile(file: file).split(' ').last().replace('\n', '').trim()
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuse some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Omni Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Omni Gateway

    - `<gateway-version>`: Version of Omni Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Omni Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.GATEWAY_NAME || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION)  {
                    error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

## Install Anypoint CLI 4.x

To install Anypoint CLI 4.x to your Docker container, add the install Anypoint CLI 4.x `stage` to
the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Install anypoint-cli-v4') {
    steps {
        script {
            sh """
                docker run --name container-anypoint-cli-v4 -d node:16 \
                sh -c " npm install -g anypoint-cli-v4 ; anypoint-cli-v4 plugins:install anypoint-cli-api-mgr-plugin; \
                while :; do sleep 1; done"
            """
            sh """
                docker exec container-anypoint-cli-v4 \
                sh -c "while ! anypoint-cli-v4 plugins 2> /dev/null | grep -q "anypoint-cli-api-mgr-plugin"; do :; done"
            """
        }
    }
}
```

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
   steps {
       script {
           sh """
               docker run --entrypoint flexctl \
                -v ${pwd()}:/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                register \
                --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --environment=${params.ENV_ID} \
                --connected=true \
                --organization=${params.ORG_ID} \
                --output-directory=/registration \
                ${params.GATEWAY_NAME}
           """

           sh """
               grep "name: registration" registration.yaml
           """
       }
   }
}


stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run --name flex-gw -d \
                -v ${pwd()}:/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION}
            """
        }
    }
}
```

## Create an API Instance

After installing Anypoint CLI 4.x, you can create an API instance and deploy it to your Omni
Gateway.

You can repeat this step to add multiple API instances. For additional API configuration flags, see
the [api-mgr:api:manage command](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr#api-mgr-api-manage).

Add the create API instance `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Create API Instance") {
    steps {
        script {
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:manage ${params.EXCHANGE_ASSET_ID} ${params.EXCHANGE_ASSET_VERSION} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --isFlex --withProxy --deploymentType=hybrid --scheme=http --port=8082 \
                --uri=https://httpbin.org:443 --path=/httpbin > api-response
            """
        }
    }
}
```

> [!NOTE] For example, this stage creates an API instance that listens on port `8082` and `/httpbin`
> path and proxies to `https://httpbin.org/443`.

## Apply a Basic Authentication Policy

After you create an API instance, you can apply policies to the API instance.

This stage applies the [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-simple) as
an example, but you can apply any Connected Mode policy. To find additional policies, see
[Included Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory).

To apply a policy:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange, for example
        `` 68ef9520-24e9-4cf2-b2f5-620025690913` ``

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.2`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The Basic Authentication: Simple
      policy uses parameters `"username"` and `"password"`.

2.  After replacing the sample content, add the apply basic authentication policy `stage` to the
    `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Apply Basic Authentication Policy to API Instance") {
    steps {
        script {
            def apiInstanceId = getAPIInstanceID('api-response')
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:policy:apply ${apiInstanceId} 'http-basic-authentication' \
                --policyVersion='1.3.1' --groupId '68ef9520-24e9-4cf2-b2f5-620025690913' \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                -c '{"username": "user", "password": "test"}'
            """
        }
    }
}
```

> [!NOTE] For example, this stage uses the policy GAV and `"configurationData"` associated with the
> [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-simple).

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            sleep(time:15, unit:"SECONDS")
            def registration_file = parseYamlFile('registration.yaml')
            def apiInstanceId = getAPIInstanceID('api-response')

            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:deploy ${apiInstanceId} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --target=${registration_file.spec.platformConnection.agentId[0]} --gatewayVersion=${params.FLEX_VERSION}
            """
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Validate Deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")

            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }

            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Omni Gateway and Archive the Registration File

Use the following code blocks to archive the registration file and remove the Docker container
running Omni Gateway. Add the `post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
    success {
        script {
            // Archive the build output artifacts.
            archiveArtifacts artifacts: 'registration.yaml'
        }
    }
    always {
        script {
            sh(script: "docker rm -f container-anypoint-cli-v4 flex-gw")
        }
    }
}
```

## See Also

- [Anypoint Platform CLI 4.x Overview](https://docs.mulesoft.com/anypoint-cli/latest/)

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/1.13/conn-reg-run-app).

- [Manage Omni Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.13/conn-manage-public-api)

<!-- document id=5302e1f91f777b86f8ca629d01448f458e8bcb84dca65208e2d87c8ce7902c80 url=/mulesoft/current/en-us/gateway/latest/conn-jenkins-cli.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Automating Omni Gateway with a Jenkins Pipeline using Anypoint CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Omni Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run an Omni Gateway and use features of the Anypoint CLI,
such as creating and deploying API instances.

To add additional features from the API Manager CLI, see
[CLI for API Manager](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr).

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] Automating your Omni Gateway with Anypoint CLI shares many similarities with Automating
> your Omni Gateway with the API Manager API. To automate your Omni Gateway using API Manger API
> requests, see
> [Automating Omni Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/latest/conn-jenkins-api).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.2`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Omni Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Omni Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Omni Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Install Anypoint CLI 4.x](#install-anypoint-cli-4-x)

4.  [Register and Run](#register-and-run).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager CLI
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions before the `pipeline` block in your Jenkinsfile:

```Jenkinsfile
def parseYamlFile(String file) {
    object = readYaml file: file
    return object
}

def getAPIInstanceID(String file) {
    return readFile(file: file).split(' ').last().replace('\n', '').trim()
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuse some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Omni Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Omni Gateway

    - `<gateway-version>`: Version of Omni Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Omni Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.GATEWAY_NAME || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION)  {
                    error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

## Install Anypoint CLI 4.x

To install Anypoint CLI 4.x to your Docker container, add the install Anypoint CLI 4.x `stage` to
the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Install anypoint-cli-v4') {
    steps {
        script {
            sh """
                docker run --name container-anypoint-cli-v4 -d node:16 \
                sh -c " npm install -g anypoint-cli-v4 ; anypoint-cli-v4 plugins:install anypoint-cli-api-mgr-plugin; \
                while :; do sleep 1; done"
            """
            sh """
                docker exec container-anypoint-cli-v4 \
                sh -c "while ! anypoint-cli-v4 plugins 2> /dev/null | grep -q "anypoint-cli-api-mgr-plugin"; do :; done"
            """
        }
    }
}
```

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
   steps {
       script {
           sh """
               docker run --entrypoint flexctl \
                -v ${pwd()}:/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                register \
                --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --environment=${params.ENV_ID} \
                --connected=true \
                --organization=${params.ORG_ID} \
                --output-directory=/registration \
                ${params.GATEWAY_NAME}
           """

           sh """
               grep "name: registration" registration.yaml
           """
       }
   }
}


stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run --name flex-gw -d \
                -v ${pwd()}:/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION}
            """
        }
    }
}
```

## Create an API Instance

After installing Anypoint CLI 4.x, you can create an API instance and deploy it to your Omni
Gateway.

You can repeat this step to add multiple API instances. For additional API configuration flags, see
the [api-mgr:api:manage command](https://docs.mulesoft.com/anypoint-cli/latest/api-mgr#api-mgr-api-manage).

Add the create API instance `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Create API Instance") {
    steps {
        script {
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:manage ${params.EXCHANGE_ASSET_ID} ${params.EXCHANGE_ASSET_VERSION} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --isFlex --withProxy --deploymentType=hybrid --scheme=http --port=8082 \
                --uri=https://httpbin.org:443 --path=/httpbin > api-response
            """
        }
    }
}
```

> [!NOTE] For example, this stage creates an API instance that listens on port `8082` and `/httpbin`
> path and proxies to `https://httpbin.org/443`.

## Apply a Basic Authentication Policy

After you create an API instance, you can apply policies to the API instance.

This stage applies the [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple) as
an example, but you can apply any Connected Mode policy. To find additional policies, see
[Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory).

To apply a policy:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange, for example
        `` 68ef9520-24e9-4cf2-b2f5-620025690913` ``

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.2`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The Basic Authentication: Simple
      policy uses parameters `"username"` and `"password"`.

2.  After replacing the sample content, add the apply basic authentication policy `stage` to the
    `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Apply Basic Authentication Policy to API Instance") {
    steps {
        script {
            def apiInstanceId = getAPIInstanceID('api-response')
            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:policy:apply ${apiInstanceId} 'http-basic-authentication' \
                --policyVersion='1.3.1' --groupId '68ef9520-24e9-4cf2-b2f5-620025690913' \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                -c '{"username": "user", "password": "test"}'
            """
        }
    }
}
```

> [!NOTE] For example, this stage uses the policy GAV and `"configurationData"` associated with the
> [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple).

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            sleep(time:15, unit:"SECONDS")
            def registration_file = parseYamlFile('registration.yaml')
            def apiInstanceId = getAPIInstanceID('api-response')

            sh """
                docker exec container-anypoint-cli-v4 anypoint-cli-v4 api-mgr:api:deploy ${apiInstanceId} \
                --client_id=${params.CONNECTED_APP_CLIENT_ID} --client_secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                --target=${registration_file.spec.platformConnection.agentId[0]} --gatewayVersion=${params.FLEX_VERSION}
            """
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Validate Deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")

            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }

            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Omni Gateway and Archive the Registration File

Use the following code blocks to archive the registration file and remove the Docker container
running Omni Gateway. Add the `post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
    success {
        script {
            // Archive the build output artifacts.
            archiveArtifacts artifacts: 'registration.yaml'
        }
    }
    always {
        script {
            sh(script: "docker rm -f container-anypoint-cli-v4 flex-gw")
        }
    }
}
```

## See Also

- [Anypoint Platform CLI 4.x Overview](https://docs.mulesoft.com/anypoint-cli/latest/)

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/latest/conn-reg-run-app).

- [Manage Omni Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/latest/conn-manage-public-api)

<!-- document id=c3a5b34f2b09ebac0bb3feea0d383d7853a222ccd207c828470003eecb6370cd url=/mulesoft/current/en-us/gateway/1.13/conn-jenkins-api.md -->

---
product: Omni Gateway
version: 1.13
---

# Automating Omni Gateway with a Jenkins Pipeline using the API Manager API

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Omni Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run an Omni Gateway and use features of the API Manager API,
such as creating and deploying API instances.

Automating your Omni Gateway in Connected Mode work flow shares many similarities with the
[Manage Omni Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.13/conn-manage-public-api) tutorial. You can use the
Jenkins Pipeline to automate the calls made to the API Manager API. To add additional features from
the
[API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/),
use the [Create an API Instance](#create-an-api-instance) and
[Apply an API Policy](#apply-an-api-policy) Pipeline stages as examples.

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] To instead automate your Omni Gateway with the Anypoint CLI, see
> [Automating Omni Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/1.13/conn-jenkins-cli).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Omni Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Omni Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Omni Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Register and Run](#register-and-run).

4.  [Obtain an Authorization Token from Access Management](#obtain-an-authorization-token-from-access-management).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager API
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions in your Jenkinsfile. Define the functions before the
`pipeline` block:

```Jenkinsfile
def parseYamlFile(String file) {
   object = readYaml file: file
   return object
}

def parseJsonFile(file) {
   object = readJSON file: file
   return object
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuses some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Omni Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Omni Gateway

    - `<gateway-version>`: Version of Omni Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`:\*Secret\* of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Omni Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION || !params.GATEWAY_NAME)  {
                error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
    steps {
        script {
            sh """
                docker run --entrypoint flexctl \
                    -v "\$(pwd)":/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                    register \
                    --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                    --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                    --environment=${params.ENV_ID} \
                    --connected=true \
                    --organization=${params.ORG_ID} \
                    --output-directory=/registration \
                    ${params.GATEWAY_NAME}
                """
                if (!fileExists('registration.yaml')) {
                    error("Registration failed")
                }
        }
    }
}

stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run -d \
                -v "\$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION} > containerId
            """
        }
    }
}
```

### Obtain an Authorization Token from Access Management

After registering and running your Omni Gateway, you must obtain a valid authorization token from
Access Management in order to authenticate subsequent requests.

To login in to Anypoint, add the Anypoint login `stage` the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Anypoint login") {
    steps {
        script {
            def cmd = """curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' -o 'login-response' \
                    --header 'Content-Type: application/json' \
                    --data-raw '{"grant_type": "client_credentials", "client_id": "${params.CONNECTED_APP_CLIENT_ID}", "client_secret": "${params.CONNECTED_APP_CLIENT_SECRET}"}'
                    """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Anypoint login failed")
            }
        }
    }
}
```

The authorization token returned in this step is saved for subsequent requests.

## Create an API Instance

Having an authorization token from Access Management enables you to create an API instance and
deploy it to your Omni Gateway.

You can repeat this step to add multiple API instances.

For example, this stage creates an API instance that listens on port `8082` and `/httpbin` path and
proxies to `https://httpbin.org/`.

To create an API instance:

1.  Collect the following information:

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI for you API instance

    - `"isCloudHub"`: Cloud Hub status, for example `null` or `true`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  After replacing the HTTP addresses, add the create API instance `stage` to the `stages` block in
    your Jenkinsfile:

```Jenkinsfile
stage("Create API instance") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def cmd = """
                curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis' -o 'api-response' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                "spec": {
                    "groupId": "${params.ORG_ID}",
                    "assetId": "${params.EXCHANGE_ASSET_ID}",
                    "version": "${params.EXCHANGE_ASSET_VERSION}"
                },
                "endpoint": {
                    "deploymentType": "HY",
                    "uri": "https://httpbin.org:443",
                    "proxyUri": "http://0.0.0.0:8082/httpbin",
                    "isCloudHub": null
                },
                "technology": "flexGateway"
                "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
                }'
            """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to create API instance")
            }
        }
    }
}
```

## Apply an API Policy

After you create an API instance, you can apply Connected Mode policies to the instance:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The `"username"` and `"password"`
      parameters are only an example. To find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory).

2.  After replacing the sample content, add the apply policy `stage` to the `stages` block in your
    Jenkinsfile:

```Jenkinsfile
stage("Apply policy") {
   steps {
       script {
           def login_response = parseJsonFile('login-response')
           def api_response = parseJsonFile('api-response')


           def cmd = """
               curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/policies' \
               --header 'Authorization: Bearer ${login_response.access_token}' \
               --header 'Content-Type: application/json' \
               --data-raw '{
                 "configurationData":{
                    "username": "user",
                    "password": "test"
                 },
                 "pointcutData": null,
                 "assetId": "<policy-asset-id>",
                 "assetVersion": "<policy-asset-id>",
                 "groupId": "<policy-group-id>"
                }'
           """


           def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
           if (status_code > 399) {
               error("Error occurred while trying to apply Basic Auth Policy to the API instance")
           }
       }
   }
}
```

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def api_response = parseJsonFile('api-response')
            def registration_file = parseYamlFile('registration.yaml')


            def cmd = """
                curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/deployments' \
                --header 'Content-Type: application/json' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --data-raw '{
                "type": "HY",
                "gatewayVersion": "${params.FLEX_VERSION}",
                "targetId": "${registration_file.spec.platformConnection.agentId[0]}",
                "environmentId": "${params.ENV_ID}"
                }'
            """


            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to deploy the API instance")
            }
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile

```Jenkinsfile
stage("Validate deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")


            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }


            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Omni Gateway and archive the registration file

Use the following code blocks to stop your Omni Gateway and archive the registration file. Add the
`post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
   success {
       script {
           // Archive the build output artifacts.
           archiveArtifacts artifacts: 'registration.yaml'
       }
   }
   always {
       script {
           if (fileExists('containerId')) {
               sh(script: "docker rm -f ${readFile(file: 'containerId')}")
           }
       }
   }
}
```

## See Also

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/1.13/conn-reg-run-app).

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

- [Manage Omni Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/1.13/conn-manage-public-api)

<!-- document id=27ec394428a3f6529f6251193e9d1924ae9536eafe10916f9c6d365d1e0a5d6c url=/mulesoft/current/en-us/gateway/latest/conn-jenkins-api.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Automating Omni Gateway with a Jenkins Pipeline using the API Manager API

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use a Jenkins Pipeline to automate the workflow for Omni Gateway in Connected Mode. With a
Jenkins Pipeline, you can register and run an Omni Gateway and use features of the API Manager API,
such as creating and deploying API instances.

Automating your Omni Gateway in Connected Mode work flow shares many similarities with the
[Manage Omni Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/latest/conn-manage-public-api) tutorial. You can use the
Jenkins Pipeline to automate the calls made to the API Manager API. To add additional features from
the
[API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/),
use the [Create an API Instance](#create-an-api-instance) and
[Apply an API Policy](#apply-an-api-policy) Pipeline stages as examples.

This tutorial has different steps with different code blocks. As you work through the steps, add the
code blocks to the same Jenkinsfile. If you are unfamiliar with the syntax used in a Jenkins
Pipeline, see the [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/).

> [!NOTE] To instead automate your Omni Gateway with the Anypoint CLI, see
> [Automating Omni Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/latest/conn-jenkins-cli).

## Before You Begin

Before you can deploy a Jenkins Pipeline, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install).

2.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    1.  Use the **App acts on its behalf (client credentials)** type and include the following
        scopes:

        - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
          **Deploy API Proxies**

        - Runtime Manager: **Read Servers** and **Manage Servers**

        - Exchange: **Exchange Viewer**

        - General: **View Organization**

    2.  Save the **Id** and **Secret** of the Connected app you configure.

3.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset (API) you want to
    create or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

4.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Omni Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Omni Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

## Initial Configuration

Before you can create and deploy an API instance to your Omni Gateway, you must complete the
following steps:

1.  [Define Useful Functions](#define-useful-functions).

2.  [Define Useful Parameters](#define-useful-parameters).

3.  [Register and Run](#register-and-run).

4.  [Obtain an Authorization Token from Access Management](#obtain-an-authorization-token-from-access-management).

After you implement these Pipeline stages, you can customize your Pipeline by making API Manager API
requests to manage APIs.

### Define Useful Functions

To begin, define these useful functions in your Jenkinsfile. Define the functions before the
`pipeline` block:

```Jenkinsfile
def parseYamlFile(String file) {
   object = readYaml file: file
   return object
}

def parseJsonFile(file) {
   object = readJSON file: file
   return object
}
```

### Define Useful Parameters

Since the commands in the Jenkins Pipeline reuses some parameters, it is helpful to define them at
the beginning of your Jenkinsfile.

Using the included parameter definitions as a template, you can also define any parameters that
additional APIs or policies need.

To define the parameters:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Omni Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Omni Gateway

    - `<gateway-version>`: Version of Omni Gateway you are using, for example `1.4.0`

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`:\*Secret\* of your connected app

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<gateway-name>`: Name of your Omni Gateway

2.  After replacing the sample content, add the parameter definitions to your Jenkinsfile to
    validate whether all parameters are present. Define the parameters in the `pipeline` block
    before the `stages` block:

    ```Jenkinsfile
    parameters {
        string(name: 'ENV_ID', defaultValue: '<your-env-id>', description: 'Your environment id')
        string(name: 'ORG_ID', defaultValue: '<your-org-id>', description: 'Your organization id')
        string(name: 'FLEX_VERSION', defaultValue: '<gateway-version>', description: 'Flex version to run')
        string(name: 'CONNECTED_APP_CLIENT_ID', defaultValue: '<connected-app-client-id>', description: 'Your connected app client id')
        string(name: 'CONNECTED_APP_CLIENT_SECRET', defaultValue: '<connected-app-client-secret', description: 'Your connected app client secret')
        string(name: 'EXCHANGE_ASSET_ID', defaultValue: '<asset-id-from-exchange>', description: 'The id of the http api exchange asset')
        string(name: 'EXCHANGE_ASSET_VERSION', defaultValue: '<asset-version>', description: 'The version of the http api exchange asset')
        string(name: 'GATEWAY_NAME', defaultValue: '<gateway-name>', description: 'Unique gateway name')
    }
    ```

3.  Add the check parameters `stage` to the `stages` block in your Jenkinsfile:

    ```Jenkinsfile
    stage('Check parameters') {
        steps {
            script {
                if (!params.ENV_ID || !params.ORG_ID || !params.FLEX_VERSION || !params.CONNECTED_APP_CLIENT_ID || !params.CONNECTED_APP_CLIENT_SECRET || !params.EXCHANGE_ASSET_ID || !params.EXCHANGE_ASSET_VERSION || !params.GATEWAY_NAME)  {
                error("Not all parameters where specified")
                }
            }
        }
    }
    ```

    If this stage fails, specify the missing parameters and rerun the Pipeline.

### Register and Run

Add the register and run stages to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage('Register flex gateway') {
    steps {
        script {
            sh """
                docker run --entrypoint flexctl \
                    -v "\$(pwd)":/registration -u 0 mulesoft/flex-gateway:${params.FLEX_VERSION} \
                    register \
                    --client-id=${params.CONNECTED_APP_CLIENT_ID} \
                    --client-secret=${params.CONNECTED_APP_CLIENT_SECRET} \
                    --environment=${params.ENV_ID} \
                    --connected=true \
                    --organization=${params.ORG_ID} \
                    --output-directory=/registration \
                    ${params.GATEWAY_NAME}
                """
                if (!fileExists('registration.yaml')) {
                    error("Registration failed")
                }
        }
    }
}

stage('Run flex gateway') {
    steps {
        script {
            sh """
                docker run -d \
                -v "\$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
                -p 8082:8082 \
                mulesoft/flex-gateway:${params.FLEX_VERSION} > containerId
            """
        }
    }
}
```

### Obtain an Authorization Token from Access Management

After registering and running your Omni Gateway, you must obtain a valid authorization token from
Access Management in order to authenticate subsequent requests.

To login in to Anypoint, add the Anypoint login `stage` the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Anypoint login") {
    steps {
        script {
            def cmd = """curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' -o 'login-response' \
                    --header 'Content-Type: application/json' \
                    --data-raw '{"grant_type": "client_credentials", "client_id": "${params.CONNECTED_APP_CLIENT_ID}", "client_secret": "${params.CONNECTED_APP_CLIENT_SECRET}"}'
                    """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Anypoint login failed")
            }
        }
    }
}
```

The authorization token returned in this step is saved for subsequent requests.

## Create an API Instance

Having an authorization token from Access Management enables you to create an API instance and
deploy it to your Omni Gateway.

You can repeat this step to add multiple API instances.

For example, this stage creates an API instance that listens on port `8082` and `/httpbin` path and
proxies to `https://httpbin.org/`.

To create an API instance:

1.  Collect the following information:

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI for you API instance

    - `"isCloudHub"`: Cloud Hub status, for example `null` or `true`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  After replacing the HTTP addresses, add the create API instance `stage` to the `stages` block in
    your Jenkinsfile:

```Jenkinsfile
stage("Create API instance") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def cmd = """
                curl -s -w "%{http_code}" --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis' -o 'api-response' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                "spec": {
                    "groupId": "${params.ORG_ID}",
                    "assetId": "${params.EXCHANGE_ASSET_ID}",
                    "version": "${params.EXCHANGE_ASSET_VERSION}"
                },
                "endpoint": {
                    "deploymentType": "HY",
                    "uri": "https://httpbin.org:443",
                    "proxyUri": "http://0.0.0.0:8082/httpbin",
                    "isCloudHub": null
                },
                "technology": "flexGateway"
                "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
                }'
            """
            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to create API instance")
            }
        }
    }
}
```

## Apply an API Policy

After you create an API instance, you can apply Connected Mode policies to the instance:

1.  Collect the following information:

    - Policy GAV

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Policy configuration data

      The configuration data fields are dependent on the policy. The `"username"` and `"password"`
      parameters are only an example. To find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory).

2.  After replacing the sample content, add the apply policy `stage` to the `stages` block in your
    Jenkinsfile:

```Jenkinsfile
stage("Apply policy") {
   steps {
       script {
           def login_response = parseJsonFile('login-response')
           def api_response = parseJsonFile('api-response')


           def cmd = """
               curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/policies' \
               --header 'Authorization: Bearer ${login_response.access_token}' \
               --header 'Content-Type: application/json' \
               --data-raw '{
                 "configurationData":{
                    "username": "user",
                    "password": "test"
                 },
                 "pointcutData": null,
                 "assetId": "<policy-asset-id>",
                 "assetVersion": "<policy-asset-id>",
                 "groupId": "<policy-group-id>"
                }'
           """


           def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
           if (status_code > 399) {
               error("Error occurred while trying to apply Basic Auth Policy to the API instance")
           }
       }
   }
}
```

## Deploy an API Instance

After you create an API instance, you can deploy the instance.

To deploy the new instance, add the deploy API `stage` to the `stages` block in your Jenkinsfile:

```Jenkinsfile
stage("Deploy API") {
    steps {
        script {
            def login_response = parseJsonFile('login-response')
            def api_response = parseJsonFile('api-response')
            def registration_file = parseYamlFile('registration.yaml')


            def cmd = """
                curl -s -w "%{http_code}" -o /dev/null --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/${params.ORG_ID}/environments/${params.ENV_ID}/apis/${api_response.id}/deployments' \
                --header 'Content-Type: application/json' \
                --header 'Authorization: Bearer ${login_response.access_token}' \
                --data-raw '{
                "type": "HY",
                "gatewayVersion": "${params.FLEX_VERSION}",
                "targetId": "${registration_file.spec.platformConnection.agentId[0]}",
                "environmentId": "${params.ENV_ID}"
                }'
            """


            def status_code = sh(returnStdout: true, script: cmd).trim().toInteger()
            if (status_code > 399) {
                error("Error occurred while trying to deploy the API instance")
            }
        }
    }
}
```

## Validate the API Instance is Deployed

After you deploy your API instance, validate whether the instance is deployed by adding the validate
deployment `stage` to the `stages` block in your Jenkinsfile

```Jenkinsfile
stage("Validate deployment") {
    steps {
        script {
            sleep(time:10, unit:"SECONDS")


            def unauthorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v", returnStdout: true).trim().toInteger()
            if (unauthorized_status_code != 401) {
                error("401 status code expected but the status code obtained is ${unauthorized_status_code}")
            }


            def authorized_status_code = sh(script: "curl -s -w \"%{http_code}\" -o /dev/null http://localhost:8082/httpbin/headers -v -u user:test", returnStdout: true).trim().toInteger()
            if (authorized_status_code != 200) {
                error("200 status code expected but the status code obtained is ${unauthorized_status_code}")
            }
        }
    }
}
```

## Stop the Omni Gateway and archive the registration file

Use the following code blocks to stop your Omni Gateway and archive the registration file. Add the
`post` block in the `pipeline` block after the `stages` block:

```Jenkinsfile
post {
   success {
       script {
           // Archive the build output artifacts.
           archiveArtifacts artifacts: 'registration.yaml'
       }
   }
   always {
       script {
           if (fileExists('containerId')) {
               sh(script: "docker rm -f ${readFile(file: 'containerId')}")
           }
       }
   }
}
```

## See Also

- [Registering and Running in Connected Mode with a Connected App](https://docs.mulesoft.com/gateway/latest/conn-reg-run-app).

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

- [Manage Omni Gateway Using the API Manager API](https://docs.mulesoft.com/gateway/latest/conn-manage-public-api)

<!-- document id=c996ddb6c4ba488677bbb7856b4b2f640eecf4c7d6acbc9acfb5dbf4e73fe7ac url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-k8-high-availability.md -->

---
product: Omni Gateway
version: 1.12
---

# Autoscale and Add Flex Gateway Replicas to a Namespace

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For high availability (HA) environments, horizontal scaling distributes load across multiple Flex
Gateway instances. By default, the Helm chart for Flex Gateway is configured with one replica. To
release more Flex Gateway replicas into a namespace, provide one of the following configurations:

- [Set a replica count](#replica-count): Set a fixed number of Flex Gateway replicas to create.

- [Configure autoscaling](#autoscale): Generate replicas automatically based on CPU, memory, and
  other settings.

Find the default Helm chart settings for Flex Gateway (flex-gateway) through one of the following
methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <helm-repository-name>/<helm-chart-name>` from a terminal window, for
  example, `helm show values flex-gateway/flex-gateway`.

## Before You Begin

Ensure that the following prerequisites are in place:

- A Flex Gateway deployment or a registered Flex Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up) or
  [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-getting-started).

- A Kubernetes cluster for your Flex Gateway deployment

## Set a Replica Count

Configure and verify the number of replicas that you require. Note that new replicas replace
existing replicas. If a newer version of Flex Gateway is available, the command replaces your older
replica versions with the latest version.

The steps to take depend on whether a Helm chart is installed.

1.  If a Helm chart for your namespace is installed, run the following command:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:00:09 2023 NAMESPACE: gateway STATUS: deployed REVISION: 27 TEST SUITE: None

2.  If the Helm chart is not installed, run the following command:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:32:50 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

3.  Verify creation of the replicas by running the following command:

    Syntax:

    kubectl get rs -n <namespace>

    Example:

    kubectl get rs -n gateway

    When successful, the command prints output similar to this example:

    NAME DESIRED CURRENT READY AGE ingress-5b7474b8f6 2 2 2 70s

## Configure Autoscaling

Horizontal Pod autoscaling generates Flex Gateway replicas automatically based on CPU, memory, and
other target and behavioral settings. For descriptions of these settings, see
[Autoscaling Parameters](#autoscaling-parameters).

### Update Your Helm Chart with an Autoscaling Configuration

To update your Helm chart with autoscaling parameters:

1.  Create a YAML file with your autoscaling configuration, modifying the settings to meet your
    requirements.

    Example:

    ```yaml
    autoscaling:
      enabled: true
    ```

    > [!NOTE] This configuration file is the minimum autoscaling configuration. To configure
    > autoscaling with more detail, see [Autoscaling Parameters](#autoscaling-parameters).

2.  If a Helm chart for your namespace is installed, run the following command to apply your
    autoscaling configuration:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Tue Apr 18
    15:46:38 2023 NAMESPACE: gateway STATUS: deployed REVISION: 33 TEST SUITE: None

3.  If the Helm chart is not installed, run the following command to apply the your autoscaling
    configuration:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    NAME: ingress LAST DEPLOYED: Tue Apr 18 15:50:29 2023 NAMESPACE: gateway STATUS: deployed
    REVISION: 1 TEST SUITE: None

4.  Verify your autoscaling configuration by running the following command:

    Syntax:

    ```kubectl
    kubectl get hpa -n <namespace>
    ```

    Example:

    ```kubectl
    kubectl get hpa -n gateway
    ```

    The command prints output similar to this example:

    NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE ingress Deployment/ingress 66%/50%, 5%/50% 2
    11 2 59s

### Autoscaling Parameters

To use autoscaling, enable Horizontal Pod Autoscaler (HPA), and configure other Helm chart settings
to define autoscaling behavior.

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>autoscaling.enabled</code></p></div></div></td><td><div><div><p>Boolean that indicates whether the Horizontal Pod Autoscaler (HPA) is enabled. Defaults to <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.minReplicas</code></p></div></div></td><td><div><div><p>The minimum number of replicas that the HPA scaler is allowed to create. Defaults to <code>2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.maxReplicas</code></p></div></div></td><td><div><div><p>The maximum number of replicas that the HPA scaler is allowed to create. Defaults to <code>11</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetCPUUtilizationPercentage</code></p></div></div></td><td><div><div><p>A resource metric that sets the average CPU usage percentage of all deployed Pods. Defaults to <code>50</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetMemoryUtilizationPercentage</code></p></div></div></td><td><div><div><p>A string representing the average memory usage percentage of all deployed Pods. Defaults to <code>nil</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior</code></p></div></div></td><td><div><div><p>A setting that supports the <code>HorizontalPodAutoscaler</code> (HPA) object in Kubernetes. HPA settings control autoscaling behavior, such as the number of application resources based on the rate of change to the workload.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior.scaleUp</code>, <code>autoscaling.behavior.scaleDown</code></p></div></div></td><td><div><div><p>Settings for autoscaling behavior when the HPA scaler increases (<code>scaleUp</code>) or decreases (<code>scaleDown</code>) the number of replicas. Define scaling behavior with nested parameters:</p></div><div><ul><li><p><code>selectPolicy</code>: If a metric of configured resources indicates that scaling is required, this setting determines when to scale Pods. This setting is necessary because Pods can contain different numbers of replicas. Valid values are <code>Disabled</code>, <code>Min</code>, and <code>Max</code>. Defaults to <code>Max</code>. The <code>Min</code> and <code>Max</code> values indicate whether to scale Pods with the lowest (<code>Min</code>) or highest (<code>Max</code>) number of replicas.</p></li><li><p><code>stabilizationWindowSeconds</code>: The minimum number of seconds to wait to rescale an application after a change to the workload. The goal is to prevent an overly aggressive or unstable response by HPA when scaling too frequently.</p></li><li><p><code>policies</code>: A list of policies that determine scaling behavior:</p><div><ul><li><p><code>type</code>: The type of value for a given policy, 'Percent' or 'Pods'.</p></li><li><p><code>value</code>: The value of the type for a given policy.</p></li><li><p><code>periodSeconds</code>: The number of seconds between scaling operations for a given policy.</p></li></ul></div></li></ul></div></div></td></tr></tbody></table>

For more information about autoscaling, see the
[Kubernetes documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).

<!-- document id=a3db016f00803cf2fad3a7912cb469897e24416a740d2f46087787e038894e32 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-k8-high-availability.md -->

---
product: Omni Gateway
version: 1.9
---

# Autoscale and Add Flex Gateway Replicas to a Namespace

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For high availability (HA) environments, horizontal scaling distributes load across multiple Flex
Gateway instances. By default, the Helm chart for Flex Gateway is configured with one replica. To
release more Flex Gateway replicas into a namespace, provide one of the following configurations:

- [Set a replica count](#replica-count): Set a fixed number of Flex Gateway replicas to create.

- [Configure autoscaling](#autoscale): Generate replicas automatically based on CPU, memory, and
  other settings.

Find the default Helm chart settings for Flex Gateway (flex-gateway) through one of the following
methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <helm-repository-name>/<helm-chart-name>` from a terminal window, for
  example, `helm show values flex-gateway/flex-gateway`.

## Before You Begin

Ensure that the following prerequisites are in place:

- A Flex Gateway deployment or a registered Flex Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up) or
  [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-getting-started).

- A Kubernetes cluster for your Flex Gateway deployment

## Set a Replica Count

Configure and verify the number of replicas that you require. Note that new replicas replace
existing replicas. If a newer version of Flex Gateway is available, the command replaces your older
replica versions with the latest version.

The steps to take depend on whether a Helm chart is installed.

1.  If a Helm chart for your namespace is installed, run the following command:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:00:09 2023 NAMESPACE: gateway STATUS: deployed REVISION: 27 TEST SUITE: None

2.  If the Helm chart is not installed, run the following command:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:32:50 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

3.  Verify creation of the replicas by running the following command:

    Syntax:

    kubectl get rs -n <namespace>

    Example:

    kubectl get rs -n gateway

    When successful, the command prints output similar to this example:

    NAME DESIRED CURRENT READY AGE ingress-5b7474b8f6 2 2 2 70s

## Configure Autoscaling

Horizontal Pod autoscaling generates Flex Gateway replicas automatically based on CPU, memory, and
other target and behavioral settings. For descriptions of these settings, see
[Autoscaling Parameters](#autoscaling-parameters).

### Update Your Helm Chart with an Autoscaling Configuration

To update your Helm chart with autoscaling parameters:

1.  Create a YAML file with your autoscaling configuration, modifying the settings to meet your
    requirements.

    Example:

    ```yaml
    autoscaling:
      enabled: true
    ```

    > [!NOTE] This configuration file is the minimum autoscaling configuration. To configure
    > autoscaling with more detail, see [Autoscaling Parameters](#autoscaling-parameters).

2.  If a Helm chart for your namespace is installed, run the following command to apply your
    autoscaling configuration:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Tue Apr 18
    15:46:38 2023 NAMESPACE: gateway STATUS: deployed REVISION: 33 TEST SUITE: None

3.  If the Helm chart is not installed, run the following command to apply the your autoscaling
    configuration:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    NAME: ingress LAST DEPLOYED: Tue Apr 18 15:50:29 2023 NAMESPACE: gateway STATUS: deployed
    REVISION: 1 TEST SUITE: None

4.  Verify your autoscaling configuration by running the following command:

    Syntax:

    ```kubectl
    kubectl get hpa -n <namespace>
    ```

    Example:

    ```kubectl
    kubectl get hpa -n gateway
    ```

    The command prints output similar to this example:

    NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE ingress Deployment/ingress 66%/50%, 5%/50% 2
    11 2 59s

### Autoscaling Parameters

To use autoscaling, enable Horizontal Pod Autoscaler (HPA), and configure other Helm chart settings
to define autoscaling behavior.

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>autoscaling.enabled</code></p></div></div></td><td><div><div><p>Boolean that indicates whether the Horizontal Pod Autoscaler (HPA) is enabled. Defaults to <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.minReplicas</code></p></div></div></td><td><div><div><p>The minimum number of replicas that the HPA scaler is allowed to create. Defaults to <code>2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.maxReplicas</code></p></div></div></td><td><div><div><p>The maximum number of replicas that the HPA scaler is allowed to create. Defaults to <code>11</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetCPUUtilizationPercentage</code></p></div></div></td><td><div><div><p>A resource metric that sets the average CPU usage percentage of all deployed Pods. Defaults to <code>50</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetMemoryUtilizationPercentage</code></p></div></div></td><td><div><div><p>A string representing the average memory usage percentage of all deployed Pods. Defaults to <code>nil</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior</code></p></div></div></td><td><div><div><p>A setting that supports the <code>HorizontalPodAutoscaler</code> (HPA) object in Kubernetes. HPA settings control autoscaling behavior, such as the number of application resources based on the rate of change to the workload.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior.scaleUp</code>, <code>autoscaling.behavior.scaleDown</code></p></div></div></td><td><div><div><p>Settings for autoscaling behavior when the HPA scaler increases (<code>scaleUp</code>) or decreases (<code>scaleDown</code>) the number of replicas. Define scaling behavior with nested parameters:</p></div><div><ul><li><p><code>selectPolicy</code>: If a metric of configured resources indicates that scaling is required, this setting determines when to scale Pods. This setting is necessary because Pods can contain different numbers of replicas. Valid values are <code>Disabled</code>, <code>Min</code>, and <code>Max</code>. Defaults to <code>Max</code>. The <code>Min</code> and <code>Max</code> values indicate whether to scale Pods with the lowest (<code>Min</code>) or highest (<code>Max</code>) number of replicas.</p></li><li><p><code>stabilizationWindowSeconds</code>: The minimum number of seconds to wait to rescale an application after a change to the workload. The goal is to prevent an overly aggressive or unstable response by HPA when scaling too frequently.</p></li><li><p><code>policies</code>: A list of policies that determine scaling behavior:</p><div><ul><li><p><code>type</code>: The type of value for a given policy, 'Percent' or 'Pods'.</p></li><li><p><code>value</code>: The value of the type for a given policy.</p></li><li><p><code>periodSeconds</code>: The number of seconds between scaling operations for a given policy.</p></li></ul></div></li></ul></div></div></td></tr></tbody></table>

For more information about autoscaling, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/workloads/autoscaling/horizontal-pod-autoscale/).

<!-- document id=e0b8ca73537d09e9a411669a8e73fed1c2b08012cf052d7e3a28a97d0d12c82d url=/mulesoft/current/en-us/gateway/1.13/gateway-k8-high-availability.md -->

---
product: Omni Gateway
version: 1.13
---

# Autoscale and Add Omni Gateway Replicas to a Namespace

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For high availability (HA) environments, horizontal scaling distributes load across multiple Omni
Gateway instances. By default, the Helm chart for Omni Gateway is configured with one replica. To
release more Omni Gateway replicas into a namespace, provide one of the following configurations:

- [Set a replica count](#replica-count): Set a fixed number of Omni Gateway replicas to create.

- [Configure autoscaling](#autoscale): Generate replicas automatically based on CPU, memory, and
  other settings.

Find the default Helm chart settings for Omni Gateway (flex-gateway) through one of the following
methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <helm-repository-name>/<helm-chart-name>` from a terminal window, for
  example, `helm show values flex-gateway/flex-gateway`.

## Before You Begin

Ensure that the following prerequisites are in place:

- An Omni Gateway deployment or a registered Omni Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up) or
  [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-k8-getting-started).

- A Kubernetes cluster for your Omni Gateway deployment

## Set a Replica Count

Configure and verify the number of replicas that you require. Note that new replicas replace
existing replicas. If a newer version of Omni Gateway is available, the command replaces your older
replica versions with the latest version.

The steps to take depend on whether a Helm chart is installed.

1.  If a Helm chart for your namespace is installed, run the following command:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:00:09 2023 NAMESPACE: gateway STATUS: deployed REVISION: 27 TEST SUITE: None

2.  If the Helm chart is not installed, run the following command:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:32:50 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

3.  Verify creation of the replicas by running the following command:

    Syntax:

    kubectl get rs -n <namespace>

    Example:

    kubectl get rs -n gateway

    When successful, the command prints output similar to this example:

    NAME DESIRED CURRENT READY AGE ingress-5b7474b8f6 2 2 2 70s

## Configure Autoscaling

Horizontal Pod autoscaling generates Omni Gateway replicas automatically based on CPU, memory, and
other target and behavioral settings. For descriptions of these settings, see
[Autoscaling Parameters](#autoscaling-parameters).

### Update Your Helm Chart with an Autoscaling Configuration

To update your Helm chart with autoscaling parameters:

1.  Create a YAML file with your autoscaling configuration, modifying the settings to meet your
    requirements.

    Example:

    ```yaml
    autoscaling:
      enabled: true
    ```

    > [!NOTE] This configuration file is the minimum autoscaling configuration. To configure
    > autoscaling with more detail, see [Autoscaling Parameters](#autoscaling-parameters).

2.  If a Helm chart for your namespace is installed, run the following command to apply your
    autoscaling configuration:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Tue Apr 18
    15:46:38 2023 NAMESPACE: gateway STATUS: deployed REVISION: 33 TEST SUITE: None

3.  If the Helm chart is not installed, run the following command to apply the your autoscaling
    configuration:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    NAME: ingress LAST DEPLOYED: Tue Apr 18 15:50:29 2023 NAMESPACE: gateway STATUS: deployed
    REVISION: 1 TEST SUITE: None

4.  Verify your autoscaling configuration by running the following command:

    Syntax:

    ```kubectl
    kubectl get hpa -n <namespace>
    ```

    Example:

    ```kubectl
    kubectl get hpa -n gateway
    ```

    The command prints output similar to this example:

    NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE ingress Deployment/ingress 66%/50%, 5%/50% 2
    11 2 59s

### Autoscaling Parameters

To use autoscaling, enable Horizontal Pod Autoscaler (HPA), and configure other Helm chart settings
to define autoscaling behavior.

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>autoscaling.enabled</code></p></div></div></td><td><div><div><p>Boolean that indicates whether the Horizontal Pod Autoscaler (HPA) is enabled. Defaults to <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.minReplicas</code></p></div></div></td><td><div><div><p>The minimum number of replicas that the HPA scaler is allowed to create. Defaults to <code>2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.maxReplicas</code></p></div></div></td><td><div><div><p>The maximum number of replicas that the HPA scaler is allowed to create. Defaults to <code>11</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetCPUUtilizationPercentage</code></p></div></div></td><td><div><div><p>A resource metric that sets the average CPU usage percentage of all deployed Pods. Defaults to <code>50</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetMemoryUtilizationPercentage</code></p></div></div></td><td><div><div><p>A string representing the average memory usage percentage of all deployed Pods. Defaults to <code>nil</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior</code></p></div></div></td><td><div><div><p>A setting that supports the <code>HorizontalPodAutoscaler</code> (HPA) object in Kubernetes. HPA settings control autoscaling behavior, such as the number of application resources based on the rate of change to the workload.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior.scaleUp</code>, <code>autoscaling.behavior.scaleDown</code></p></div></div></td><td><div><div><p>Settings for autoscaling behavior when the HPA scaler increases (<code>scaleUp</code>) or decreases (<code>scaleDown</code>) the number of replicas. Define scaling behavior with nested parameters:</p></div><div><ul><li><p><code>selectPolicy</code>: If a metric of configured resources indicates that scaling is required, this setting determines when to scale Pods. This setting is necessary because Pods can contain different numbers of replicas. Valid values are <code>Disabled</code>, <code>Min</code>, and <code>Max</code>. Defaults to <code>Max</code>. The <code>Min</code> and <code>Max</code> values indicate whether to scale Pods with the lowest (<code>Min</code>) or highest (<code>Max</code>) number of replicas.</p></li><li><p><code>stabilizationWindowSeconds</code>: The minimum number of seconds to wait to rescale an application after a change to the workload. The goal is to prevent an overly aggressive or unstable response by HPA when scaling too frequently.</p></li><li><p><code>policies</code>: A list of policies that determine scaling behavior:</p><div><ul><li><p><code>type</code>: The type of value for a given policy, 'Percent' or 'Pods'.</p></li><li><p><code>value</code>: The value of the type for a given policy.</p></li><li><p><code>periodSeconds</code>: The number of seconds between scaling operations for a given policy.</p></li></ul></div></li></ul></div></div></td></tr></tbody></table>

For more information about autoscaling, see the
[Kubernetes documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).

<!-- document id=43051c36f756b90fbf2de7cccefa28720010163a8bf84b3cb40c2dc190ce2335 url=/mulesoft/current/en-us/gateway/latest/gateway-k8-high-availability.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Autoscale and Add Omni Gateway Replicas to a Namespace

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For high availability (HA) environments, horizontal scaling distributes load across multiple Omni
Gateway instances. By default, the Helm chart for Omni Gateway is configured with one replica. To
release more Omni Gateway replicas into a namespace, provide one of the following configurations:

- [Set a replica count](#replica-count): Set a fixed number of Omni Gateway replicas to create.

- [Configure autoscaling](#autoscale): Generate replicas automatically based on CPU, memory, and
  other settings.

Find the default Helm chart settings for Omni Gateway (flex-gateway) through one of the following
methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <helm-repository-name>/<helm-chart-name>` from a terminal window, for
  example, `helm show values flex-gateway/flex-gateway`.

## Before You Begin

Ensure that the following prerequisites are in place:

- An Omni Gateway deployment or a registered Omni Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up) or
  [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-k8-getting-started).

- A Kubernetes cluster for your Omni Gateway deployment

## Set a Replica Count

Configure and verify the number of replicas that you require. Note that new replicas replace
existing replicas. If a newer version of Omni Gateway is available, the command replaces your older
replica versions with the latest version.

The steps to take depend on whether a Helm chart is installed.

1.  If a Helm chart for your namespace is installed, run the following command:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:00:09 2023 NAMESPACE: gateway STATUS: deployed REVISION: 27 TEST SUITE: None

2.  If the Helm chart is not installed, run the following command:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ --set replicaCount=<number of replicas>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    --set replicaCount=2
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Apr 17
    15:32:50 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

3.  Verify creation of the replicas by running the following command:

    Syntax:

    kubectl get rs -n <namespace>

    Example:

    kubectl get rs -n gateway

    When successful, the command prints output similar to this example:

    NAME DESIRED CURRENT READY AGE ingress-5b7474b8f6 2 2 2 70s

## Configure Autoscaling

Horizontal Pod autoscaling generates Omni Gateway replicas automatically based on CPU, memory, and
other target and behavioral settings. For descriptions of these settings, see
[Autoscaling Parameters](#autoscaling-parameters).

### Update Your Helm Chart with an Autoscaling Configuration

To update your Helm chart with autoscaling parameters:

1.  Create a YAML file with your autoscaling configuration, modifying the settings to meet your
    requirements.

    Example:

    ```yaml
    autoscaling:
      enabled: true
    ```

    > [!NOTE] This configuration file is the minimum autoscaling configuration. To configure
    > autoscaling with more detail, see [Autoscaling Parameters](#autoscaling-parameters).

2.  If a Helm chart for your namespace is installed, run the following command to apply your
    autoscaling configuration:

    Syntax:

    helm -n <namespace> upgrade \\ <release-name> <helm-repository-name>/<helm-chart-name> \\
    --reuse-values \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway upgrade \
    ingress flex-gateway/flex-gateway \
    --reuse-values \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Tue Apr 18
    15:46:38 2023 NAMESPACE: gateway STATUS: deployed REVISION: 33 TEST SUITE: None

3.  If the Helm chart is not installed, run the following command to apply the your autoscaling
    configuration:

    Syntax:

    helm -n <namespace> \\ upgrade -i --create-namespace \\ <release-name>
    <helm-repository-name>/<helm-chart-name> \\ --set-file registration.content=<registration file>
    \\ -f <your-autoscaling-configuration-yaml>

    Example:

    ```helm
    helm -n gateway \
    upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml \
    -f autoscaling.yaml
    ```

    When successful, the command prints output similar to this example:

    NAME: ingress LAST DEPLOYED: Tue Apr 18 15:50:29 2023 NAMESPACE: gateway STATUS: deployed
    REVISION: 1 TEST SUITE: None

4.  Verify your autoscaling configuration by running the following command:

    Syntax:

    ```kubectl
    kubectl get hpa -n <namespace>
    ```

    Example:

    ```kubectl
    kubectl get hpa -n gateway
    ```

    The command prints output similar to this example:

    NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE ingress Deployment/ingress 66%/50%, 5%/50% 2
    11 2 59s

### Autoscaling Parameters

To use autoscaling, enable Horizontal Pod Autoscaler (HPA), and configure other Helm chart settings
to define autoscaling behavior.

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>autoscaling.enabled</code></p></div></div></td><td><div><div><p>Boolean that indicates whether the Horizontal Pod Autoscaler (HPA) is enabled. Defaults to <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.minReplicas</code></p></div></div></td><td><div><div><p>The minimum number of replicas that the HPA scaler is allowed to create. Defaults to <code>2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.maxReplicas</code></p></div></div></td><td><div><div><p>The maximum number of replicas that the HPA scaler is allowed to create. Defaults to <code>11</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetCPUUtilizationPercentage</code></p></div></div></td><td><div><div><p>A resource metric that sets the average CPU usage percentage of all deployed Pods. Defaults to <code>50</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.targetMemoryUtilizationPercentage</code></p></div></div></td><td><div><div><p>A string representing the average memory usage percentage of all deployed Pods. Defaults to <code>nil</code>.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior</code></p></div></div></td><td><div><div><p>A setting that supports the <code>HorizontalPodAutoscaler</code> (HPA) object in Kubernetes. HPA settings control autoscaling behavior, such as the number of application resources based on the rate of change to the workload.</p></div></div></td></tr><tr><td><div><div><p><code>autoscaling.behavior.scaleUp</code>, <code>autoscaling.behavior.scaleDown</code></p></div></div></td><td><div><div><p>Settings for autoscaling behavior when the HPA scaler increases (<code>scaleUp</code>) or decreases (<code>scaleDown</code>) the number of replicas. Define scaling behavior with nested parameters:</p></div><div><ul><li><p><code>selectPolicy</code>: If a metric of configured resources indicates that scaling is required, this setting determines when to scale Pods. This setting is necessary because Pods can contain different numbers of replicas. Valid values are <code>Disabled</code>, <code>Min</code>, and <code>Max</code>. Defaults to <code>Max</code>. The <code>Min</code> and <code>Max</code> values indicate whether to scale Pods with the lowest (<code>Min</code>) or highest (<code>Max</code>) number of replicas.</p></li><li><p><code>stabilizationWindowSeconds</code>: The minimum number of seconds to wait to rescale an application after a change to the workload. The goal is to prevent an overly aggressive or unstable response by HPA when scaling too frequently.</p></li><li><p><code>policies</code>: A list of policies that determine scaling behavior:</p><div><ul><li><p><code>type</code>: The type of value for a given policy, 'Percent' or 'Pods'.</p></li><li><p><code>value</code>: The value of the type for a given policy.</p></li><li><p><code>periodSeconds</code>: The number of seconds between scaling operations for a given policy.</p></li></ul></div></li></ul></div></div></td></tr></tbody></table>

For more information about autoscaling, see the
[Kubernetes documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).

<!-- document id=2c94f494a7229752e7f13300daac72c4abbc2ff8a4fd64525ff859342d8e864f url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-aws-lambda.md -->

---
product: Omni Gateway
version: 1.12
---

# AWS Lambda Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>AWS Lambda</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Triggers an AWS Lambda function from a standard HTTP request</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Transformation</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>502 - Bad Gateway, requests are blocked due to circuit breaker activation</p></div></div></td></tr></tbody></table>

## Summary

The AWS Lambda policy triggers an AWS Lambda function from a standard HTTP request. Pass the HTTP
request payload as is or wrapped in a JSON schema.

The AWS Lambda policy is an extension of the AWS Lambda filter native to Envoy. To learn more about
the AWS Lambda filter, see
[AWS Lambda Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_lambda_filter).
Not all AWS Lambda filter parameters are available to the AWS Lambda policy. To find what parameters
are configurable, see [Configuring Policy Parameters](#configuring-policy-parameters).

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: <string> // REQUIRED
    payloadPassthrough: <boolean> // REQUIRED
    invocationMode: <string> // REQUIRED
    authenticationMode: <string> // REQUIRED
    credentialProfile: <string> // OPTIONAL
    credentials:
      accessKeyId: <string> // OPTIONAL
      secretAccessKey: <string> // OPTIONAL
      sessionToken: <string> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>arn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>payloadPassthrough</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>By default, Flex sends the request to the AWS Lambda function wrapped in JSON. When <code>payloadPassthrough</code> is enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p><code>invocationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>sync</p></div></div></td><td><div><div><p>The way to invoke the Lambda function, either <code>sync</code> or <code>async</code>. For <code>sync</code>, Flex Gateway awaits the AWS response. For <code>async</code>, Flex Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p><code>authenticationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <code>default</code>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <code>profile</code>, profile from AWS credential file; <code>static</code>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p><code>credentialProfile</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the credential <code>profile</code>. Only for <code>profile</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Configures the <code>static</code> credentials object. Only for <code>static</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials.accessKeyId</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p><code>credentials.secretAccessKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p><code>credentials.sessionToken</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: rn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;
    payloadPassthrough: true
    invocationMode: sync
    authenticationMode: static
    credentials:
      accessKeyId: id
      secretAccessKey: secret
      sessionToken: token
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>The ARN of the AWS Lambda</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Payload passthrough</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>By default, Flex sends the request to the AWS Lambda function wrapped in JSON. When enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p>Determines the way to invoke the Lambda function</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>The way to invoke the Lambda function. For <strong>Sync</strong>, Flex Gateway awaits the AWS response. For <strong>Async</strong>, Flex Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p>Determines origin of credentials</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <strong>Default</strong>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <strong>Profile</strong>, profile from AWS credential file; <strong>Static</strong>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p>Credentials profile</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Specifies the credential profile. Only for <strong>Profile</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>Credentials</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Configures the static credentials. Only for <strong>Static</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>AccessKeyId</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p>SecretAccessKey</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p>SessionToken</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

<!-- document id=3171d24cdc3321a1b3ce84b0838d0f864f4e7752119ff9ab1907a015d5b596ff url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-aws-lambda.md -->

---
product: Omni Gateway
version: 1.13
---

# AWS Lambda Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>AWS Lambda</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Triggers an AWS Lambda function from a standard HTTP request</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Transformation</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-lambda-release-notes">AWS Lambda</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>502 - Bad Gateway, requests are blocked due to circuit breaker activation</p></div></div></td></tr></tbody></table>

## Summary

The AWS Lambda policy triggers an AWS Lambda function from a standard HTTP request. Pass the HTTP
request payload as is or wrapped in a JSON schema.

The AWS Lambda policy is an extension of the AWS Lambda filter native to Envoy. To learn more about
the AWS Lambda filter, see
[AWS Lambda Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_lambda_filter).
Not all AWS Lambda filter parameters are available to the AWS Lambda policy. To find what parameters
are configurable, see [Configuring Policy Parameters](#configuring-policy-parameters).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: <string> // REQUIRED
    payloadPassthrough: <boolean> // REQUIRED
    invocationMode: <string> // REQUIRED
    authenticationMode: <string> // REQUIRED
    credentialProfile: <string> // OPTIONAL
    credentials:
      accessKeyId: <string> // OPTIONAL
      secretAccessKey: <string> // OPTIONAL
      sessionToken: <string> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>arn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>payloadPassthrough</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>By default, Omni sends the request to the AWS Lambda function wrapped in JSON. When <code>payloadPassthrough</code> is enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p><code>invocationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>sync</p></div></div></td><td><div><div><p>The way to invoke the Lambda function, either <code>sync</code> or <code>async</code>. For <code>sync</code>, Omni Gateway awaits the AWS response. For <code>async</code>, Omni Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p><code>authenticationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <code>default</code>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <code>profile</code>, profile from AWS credential file; <code>static</code>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p><code>credentialProfile</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the credential <code>profile</code>. Only for <code>profile</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Configures the <code>static</code> credentials object. Only for <code>static</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials.accessKeyId</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p><code>credentials.secretAccessKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p><code>credentials.sessionToken</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: rn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;
    payloadPassthrough: true
    invocationMode: sync
    authenticationMode: static
    credentials:
      accessKeyId: id
      secretAccessKey: secret
      sessionToken: token
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>The ARN of the AWS Lambda</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Payload passthrough</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>By default, Omni sends the request to the AWS Lambda function wrapped in JSON. When enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p>Determines the way to invoke the Lambda function</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>The way to invoke the Lambda function. For <strong>Sync</strong>, Omni Gateway awaits the AWS response. For <strong>Async</strong>, Omni Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p>Determines origin of credentials</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <strong>Default</strong>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <strong>Profile</strong>, profile from AWS credential file; <strong>Static</strong>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p>Credentials profile</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Specifies the credential profile. Only for <strong>Profile</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>Credentials</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Configures the static credentials. Only for <strong>Static</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>AccessKeyId</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p>SecretAccessKey</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p>SessionToken</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

<!-- document id=7a2cda08a23841ed839bae0ede6d537aefd5b6f4e6c1558ac45648cc8be380a6 url=/mulesoft/current/en-us/gateway/1.9/policies-outbound-aws-lambda.md -->

---
product: Omni Gateway
version: 1.9
---

# AWS Lambda Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>AWS Lambda</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Triggers an AWS Lambda function from a standard HTTP request</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Transformation</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>502 - Bad Gateway, requests are blocked due to circuit breaker activation</p></div></div></td></tr></tbody></table>

## Summary

The AWS Lambda policy triggers an AWS Lambda function from a standard HTTP request. Pass the HTTP
request payload as is or wrapped in a JSON schema.

The AWS Lambda policy is an extension of the AWS Lambda filter native to Envoy. To learn more about
the AWS Lambda filter, see
[AWS Lambda Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_lambda_filter).
Not all AWS Lambda filter parameters are available to the AWS Lambda policy. To find what parameters
are configurable, see [Configuring Policy Parameters](#configuring-policy-parameters).

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: <string> // REQUIRED
    payloadPassthrough: <boolean> // REQUIRED
    invocationMode: <string> // REQUIRED
    authenticationMode: <string> // REQUIRED
    credentialProfile: <string> // OPTIONAL
    credentials:
      accessKeyId: <string> // OPTIONAL
      secretAccessKey: <string> // OPTIONAL
      sessionToken: <string> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>arn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>payloadPassthrough</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>By default, Flex sends the request to the AWS Lambda function wrapped in JSON. When <code>payloadPassthrough</code> is enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p><code>invocationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>sync</p></div></div></td><td><div><div><p>The way to invoke the Lambda function, either <code>sync</code> or <code>async</code>. For <code>sync</code>, Flex Gateway awaits the AWS response. For <code>async</code>, Flex Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p><code>authenticationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <code>default</code>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <code>profile</code>, profile from AWS credential file; <code>static</code>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p><code>credentialProfile</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the credential <code>profile</code>. Only for <code>profile</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Configures the <code>static</code> credentials object. Only for <code>static</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials.accessKeyId</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p><code>credentials.secretAccessKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p><code>credentials.sessionToken</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: rn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;
    payloadPassthrough: true
    invocationMode: sync
    authenticationMode: static
    credentials:
      accessKeyId: id
      secretAccessKey: secret
      sessionToken: token
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>The ARN of the AWS Lambda</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Payload passthrough</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>By default, Flex sends the request to the AWS Lambda function wrapped in JSON. When enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p>Determines the way to invoke the Lambda function</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>The way to invoke the Lambda function. For <strong>Sync</strong>, Flex Gateway awaits the AWS response. For <strong>Async</strong>, Flex Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p>Determines origin of credentials</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <strong>Default</strong>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <strong>Profile</strong>, profile from AWS credential file; <strong>Static</strong>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p>Credentials profile</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Specifies the credential profile. Only for <strong>Profile</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>Credentials</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Configures the static credentials. Only for <strong>Static</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>AccessKeyId</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p>SecretAccessKey</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p>SessionToken</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

<!-- document id=dae1e315c53e0f6f505b691732130de767a0c8f6f7d6382d927d6917085b752b url=/mulesoft/current/en-us/gateway/latest/policies-outbound-aws-lambda.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# AWS Lambda Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>AWS Lambda</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Triggers an AWS Lambda function from a standard HTTP request</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Transformation</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-lambda-release-notes">AWS Lambda</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>502 - Bad Gateway, requests are blocked due to circuit breaker activation</p></div></div></td></tr></tbody></table>

## Summary

The AWS Lambda policy triggers an AWS Lambda function from a standard HTTP request. Pass the HTTP
request payload as is or wrapped in a JSON schema.

The AWS Lambda policy is an extension of the AWS Lambda filter native to Envoy. To learn more about
the AWS Lambda filter, see
[AWS Lambda Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/aws_lambda_filter).
Not all AWS Lambda filter parameters are available to the AWS Lambda policy. To find what parameters
are configurable, see [Configuring Policy Parameters](#configuring-policy-parameters).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: <string> // REQUIRED
    payloadPassthrough: <boolean> // REQUIRED
    invocationMode: <string> // REQUIRED
    authenticationMode: <string> // REQUIRED
    credentialProfile: <string> // OPTIONAL
    credentials:
      accessKeyId: <string> // OPTIONAL
      secretAccessKey: <string> // OPTIONAL
      sessionToken: <string> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>arn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>payloadPassthrough</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>By default, Omni sends the request to the AWS Lambda function wrapped in JSON. When <code>payloadPassthrough</code> is enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p><code>invocationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>sync</p></div></div></td><td><div><div><p>The way to invoke the Lambda function, either <code>sync</code> or <code>async</code>. For <code>sync</code>, Omni Gateway awaits the AWS response. For <code>async</code>, Omni Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p><code>authenticationMode</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <code>default</code>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <code>profile</code>, profile from AWS credential file; <code>static</code>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p><code>credentialProfile</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the credential <code>profile</code>. Only for <code>profile</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Configures the <code>static</code> credentials object. Only for <code>static</code> authentication mode.</p></div></div></td></tr><tr><td><div><div><p><code>credentials.accessKeyId</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p><code>credentials.secretAccessKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p><code>credentials.sessionToken</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

```yaml
- policyRef:
    name: native-aws-lambda
  config:
    arn: rn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;
    payloadPassthrough: true
    invocationMode: sync
    authenticationMode: static
    credentials:
      accessKeyId: id
      secretAccessKey: secret
      sessionToken: token
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>The ARN of the AWS Lambda</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS Lambda ARN in this format: <code>arn:&lt;partition&gt;:lambda:&lt;region&gt;:&lt;account-number&gt;:function:&lt;function-name&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Payload passthrough</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>By default, Omni sends the request to the AWS Lambda function wrapped in JSON. When enabled, the request is sent as is.</p></div></div></td></tr><tr><td><div><div><p>Determines the way to invoke the Lambda function</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>The way to invoke the Lambda function. For <strong>Sync</strong>, Omni Gateway awaits the AWS response. For <strong>Async</strong>, Omni Gateway doesn’t wait for the response from AWS.</p></div></div></td></tr><tr><td><div><div><p>Determines origin of credentials</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Determines the mode of authentication. Options are: <strong>Default</strong>, uses in order credential AWS environment variables, AWS credential file, AWS roles; <strong>Profile</strong>, profile from AWS credential file; <strong>Static</strong>, credentials configured in the policy.</p></div></div></td></tr><tr><td><div><div><p>Credentials profile</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Specifies the credential profile. Only for <strong>Profile</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>Credentials</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Configures the static credentials. Only for <strong>Static</strong> authentication mode.</p></div></div></td></tr><tr><td><div><div><p>AccessKeyId</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key ID</p></div></div></td></tr><tr><td><div><div><p>SecretAccessKey</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>AWS access key</p></div></div></td></tr><tr><td><div><div><p>SessionToken</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Session token</p></div></div></td></tr></tbody></table>

<!-- document id=d152438d063d9b5a534bc1192d9e36761c4b8c2ca5c81ca30b1cac84a00cc2dc url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-aws-signature.md -->

# AWS Request Signature Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS Request Signature</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A)</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Flex Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.11.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy. Error codes are returned from the upstream service.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The AWS Request Signature policy signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A) authentication. This policy injects the required AWS signature headers into requests to authenticate with AWS services, such as Amazon S3, Amazon API Gateway, or other AWS HTTP endpoints.

The AWS Request Signature policy is an extension of the AWS Request Signing filter native to Envoy. To learn more about the AWS Request Signing filter, see [AWS Request Signing Filter](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto). Not all AWS Request Signing filter parameters are available to the AWS Request Signature policy. To find what parameters are configurable, see [Configuring Policy Parameters](#configuring-policy-parameters).

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

```yaml
- policyRef:
    name: native-aws-signature-flex
  config:
    serviceName: <string> // REQUIRED
    region: <string> // REQUIRED
    useUnsignedPayload: <boolean> // OPTIONAL
    signingAlgorithm: <string> // REQUIRED
    matchExcludedHeaders:
      - <string> // OPTIONAL
    authenticationMode: <string> // REQUIRED
    credentialsFileProvider: <object> // OPTIONAL
    inlineCredentialProvider: <object> // OPTIONAL
```

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">If you don’t configure required parameters, the policy the default value. If the policy doesn’t have a default value, there is a configuration error.</td></tr></tbody></table>

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>serviceName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The service namespace of the HTTP endpoint. For example: <code>s3</code>, <code>execute-api</code>, or <code>ec2</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>region</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The AWS region of the service hosting the HTTP endpoint.<br>
For <code>AWS_SIGV4</code>, this is a standard AWS region. For example: <code>us-west-2</code>.<br>
For <code>AWS_SIGV4A</code>, this is a region set of comma-separated region names (<code>us-west-2</code>), wildcards (<code><strong></strong></code><strong>), or region strings with wildcards (<code>us-east-</code></strong>). A region set enables a signed request to be sent to multiple regions.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>useUnsignedPayload</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Use the literal string <code>UNSIGNED-PAYLOAD</code> to calculate the payload hash instead of buffering the request to calculate the hash. Not all services support this option.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>matchExcludedHeaders</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>A list of request header to exclude from signing. Match by any <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/matcher/v3/string.proto#envoy-v3-api-msg-type-matcher-v3-stringmatcher">Envoy StringMatcher pattern</a>. For example:</p>
</div>
<div class="paragraph">
<p>+</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">matchExcludedHeaders:
  - prefix: x-envoy
  - exact: x-custom-header
  - exact: x-trace-id</code></pre>
</div>
</div>
<div class="paragraph">
<p>+
In the example, the policy does not sign headers that start with <code>x-envoy</code> and the <code>x-custom-header</code> and <code>x-trace-id</code> headers.</p>
</div>
<div class="paragraph">
<p>+
By default, Envoy excludes the <code>x-forwarded-for</code>, <code>x-forwarded-proto</code>, and <code>x-amzn-trace-id</code> headers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>signingAlgorithm</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>AWS_SIGV4</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The signing algorithm to use, either <code>AWS_SIGV4</code> or <code>AWS_SIGV4A</code>. <code>AWS_SIGV4A</code> supports multi-region requests.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>authenticationMode</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>default</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Determines the mode of authentication for AWS credentials. Options are:<br>
* <code>default</code>: Uses the AWS credential chain in the order of environment variables, AWS credential file, then AWS roles.<br>
* <code>profile</code>: Uses a specific profile from the AWS credential file.<br>
* <code>static</code>: Uses statically configured credentials provided in <code>inlineCredentialProvider</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>credentialsFileProvider</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration for using credentials from an AWS credential file. Required when <code>authenticationMode</code> is <code>profile</code>. See <a href="#credential-provider-configuration">Credential Provider Configuration</a> for details.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>inlineCredentialProvider</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration for statically configured credentials. Required when <code>authenticationMode</code> is <code>static</code>. See <a href="#credential-provider-configuration">Credential Provider Configuration</a> for details.</p>
</div></div></td>
</tr>
</tbody>
</table>

### [](#credential-provider-configuration)Credential Provider Configuration

The credential provider configuration depends on the `authenticationMode` setting:

- **`default`**: No additional configuration needed. The policy uses the AWS credential chain (environment variables, AWS credential file, or AWS roles).
- **`profile`**: Use `credentialsFileProvider` to specify the AWS credential file and profile.
- **`static`**: Use `inlineCredentialProvider` to provide credentials directly in the configuration.

#### [](#credentials-file-provider)Credentials File Provider

Use `credentialsFileProvider` when `authenticationMode` is set to `profile`:

```yaml
credentialsFileProvider:
  credentialsDataSource:
    filename: <string> // REQUIRED
  profile: <string> // OPTIONAL
```

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>credentialsDataSource.filename</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Path to the AWS credential file. For example: <code>~/.aws/credentials</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>profile</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>default</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The AWS profile name to use from the credential file.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#inline-credential-provider)Inline Credential Provider

Use `inlineCredentialProvider` when `authenticationMode` is set to `static`:

```yaml
inlineCredentialProvider:
  accessKeyId: <string> // REQUIRED
  secretAccessKey: <string> // REQUIRED
  sessionToken: <string> // OPTIONAL
```

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>accessKeyId</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS access key ID.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>secretAccessKey</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS secret access key.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>sessionToken</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS session token (required for temporary credentials).</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-examples)Resource Configuration Examples

- Basic configuration with default authentication:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: default
    ```
- Configuration with static credentials:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: execute-api
        region: us-east-1
        signingAlgorithm: AWS_SIGV4
        authenticationMode: static
        inlineCredentialProvider:
          accessKeyId: AKIAIOSFODNN7EXAMPLE
          secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    ```
- Configuration with profile authentication:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: profile
        credentialsFileProvider:
          credentialsDataSource:
            filename: ~/.aws/credentials
          profile: my-profile
    ```
- Configuration with SigV4A and unsigned payload:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: "*"
        signingAlgorithm: AWS_SIGV4A
        authenticationMode: default
        useUnsignedPayload: true
    ```
- Configuration with excluded headers:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: default
        matchExcludedHeaders:
          - prefix: x-envoy
          - exact: x-custom-header
          - exact: x-trace-id
    ```

### [](#connected-mode)Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Service name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The service namespace of the HTTP endpoint. For example: <code>s3</code>, <code>execute-api</code>, or <code>ec2</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Region</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The AWS region string for the service. For SigV4, use a standard region. For example: <code>us-west-2</code>. For SigV4A, use a region set of comma-separated region names (<code>us-west-2</code>), wildcards (<code><strong></strong></code><strong>), or region strings with wildcards (<code>us-east-</code></strong>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Use unsigned payload</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Instead of buffering the request to calculate the payload hash, use the literal string <code>UNSIGNED-PAYLOAD</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signing algorithm</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The signing algorithm to use: <code>AWS_SIGV4</code> or <code>AWS_SIGV4A</code>. <code>AWS_SIGV4A</code> supports multi-region requests.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Match excluded headers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A list of request headers to exclude from signing. Match by any Envoy StringMatcher pattern. For example: <code>prefix: x-envoy</code>, <code>exact: x-custom-header</code>, or <code>exact: x-trace-id</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Authentication mode</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Determines the mode of authentication for AWS credentials. Options: <code>default</code> (uses AWS credential chain: environment variables, AWS credential file, AWS roles), <code>profile</code> (uses a specific profile from the AWS credential file), or <code>static</code> (uses statically configured credentials).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Credentials file provider</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configuration for using credentials from an AWS credential file (required when authentication mode is <code>profile</code>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Credentials file</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Path to the AWS credential file. For example: <code>~/.aws/credentials</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using credentials file provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Profile</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The AWS profile name to use from the credential file.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Inline credential provider</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configuration for statically configured credentials (required when authentication mode is <code>static</code>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Access key ID</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS access key ID when using inline credential provider.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using inline credential provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Secret access key</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS secret access key when using inline credential provider.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using inline credential provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Session token</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS session token when using inline credential provider with temporary credentials.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

<!-- document id=7440363eb84023c7ffd79ae01b215050745817a34d5aa3a7b4629975f385dd07 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-aws-signature.md -->

# AWS Request Signature Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS Request Signature</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A)</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.11.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-signature-release-notes" class="xref page">AWS Request Signature</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy. Error codes are returned from the upstream service.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The AWS Request Signature policy signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A) authentication. This policy injects the required AWS signature headers into requests to authenticate with AWS services, such as Amazon S3, Amazon API Gateway, or other AWS HTTP endpoints.

The AWS Request Signature policy is an extension of the AWS Request Signing filter native to Envoy. To learn more about the AWS Request Signing filter, see [AWS Request Signing Filter](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto). Not all AWS Request Signing filter parameters are available to the AWS Request Signature policy. To find what parameters are configurable, see [Configuring Policy Parameters](#configuring-policy-parameters).

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

```yaml
- policyRef:
    name: native-aws-signature-flex
  config:
    serviceName: <string> // REQUIRED
    region: <string> // REQUIRED
    useUnsignedPayload: <boolean> // OPTIONAL
    signingAlgorithm: <string> // REQUIRED
    matchExcludedHeaders:
      - <string> // OPTIONAL
    authenticationMode: <string> // REQUIRED
    credentialsFileProvider: <object> // OPTIONAL
    inlineCredentialProvider: <object> // OPTIONAL
```

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">If you don’t configure required parameters, the policy the default value. If the policy doesn’t have a default value, there is a configuration error.</td></tr></tbody></table>

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>serviceName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The service namespace of the HTTP endpoint. For example: <code>s3</code>, <code>execute-api</code>, or <code>ec2</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>region</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The AWS region of the service hosting the HTTP endpoint.<br>
For <code>AWS_SIGV4</code>, this is a standard AWS region. For example: <code>us-west-2</code>.<br>
For <code>AWS_SIGV4A</code>, this is a region set of comma-separated region names (<code>us-west-2</code>), wildcards (<code><strong></strong></code><strong>), or region strings with wildcards (<code>us-east-</code></strong>). A region set enables a signed request to be sent to multiple regions.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>useUnsignedPayload</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Use the literal string <code>UNSIGNED-PAYLOAD</code> to calculate the payload hash instead of buffering the request to calculate the hash. Not all services support this option.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>matchExcludedHeaders</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>A list of request header to exclude from signing. Match by any <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/matcher/v3/string.proto#envoy-v3-api-msg-type-matcher-v3-stringmatcher">Envoy StringMatcher pattern</a>. For example:</p>
</div>
<div class="paragraph">
<p>+</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">matchExcludedHeaders:
  - prefix: x-envoy
  - exact: x-custom-header
  - exact: x-trace-id</code></pre>
</div>
</div>
<div class="paragraph">
<p>+
In the example, the policy does not sign headers that start with <code>x-envoy</code> and the <code>x-custom-header</code> and <code>x-trace-id</code> headers.</p>
</div>
<div class="paragraph">
<p>+
By default, Envoy excludes the <code>x-forwarded-for</code>, <code>x-forwarded-proto</code>, and <code>x-amzn-trace-id</code> headers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>signingAlgorithm</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>AWS_SIGV4</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The signing algorithm to use, either <code>AWS_SIGV4</code> or <code>AWS_SIGV4A</code>. <code>AWS_SIGV4A</code> supports multi-region requests.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>authenticationMode</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>default</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Determines the mode of authentication for AWS credentials. Options are:<br>
* <code>default</code>: Uses the AWS credential chain in the order of environment variables, AWS credential file, then AWS roles.<br>
* <code>profile</code>: Uses a specific profile from the AWS credential file.<br>
* <code>static</code>: Uses statically configured credentials provided in <code>inlineCredentialProvider</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>credentialsFileProvider</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration for using credentials from an AWS credential file. Required when <code>authenticationMode</code> is <code>profile</code>. See <a href="#credential-provider-configuration">Credential Provider Configuration</a> for details.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>inlineCredentialProvider</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration for statically configured credentials. Required when <code>authenticationMode</code> is <code>static</code>. See <a href="#credential-provider-configuration">Credential Provider Configuration</a> for details.</p>
</div></div></td>
</tr>
</tbody>
</table>

### [](#credential-provider-configuration)Credential Provider Configuration

The credential provider configuration depends on the `authenticationMode` setting:

- **`default`**: No additional configuration needed. The policy uses the AWS credential chain (environment variables, AWS credential file, or AWS roles).
- **`profile`**: Use `credentialsFileProvider` to specify the AWS credential file and profile.
- **`static`**: Use `inlineCredentialProvider` to provide credentials directly in the configuration.

#### [](#credentials-file-provider)Credentials File Provider

Use `credentialsFileProvider` when `authenticationMode` is set to `profile`:

```yaml
credentialsFileProvider:
  credentialsDataSource:
    filename: <string> // REQUIRED
  profile: <string> // OPTIONAL
```

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>credentialsDataSource.filename</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Path to the AWS credential file. For example: <code>~/.aws/credentials</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>profile</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>default</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The AWS profile name to use from the credential file.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#inline-credential-provider)Inline Credential Provider

Use `inlineCredentialProvider` when `authenticationMode` is set to `static`:

```yaml
inlineCredentialProvider:
  accessKeyId: <string> // REQUIRED
  secretAccessKey: <string> // REQUIRED
  sessionToken: <string> // OPTIONAL
```

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>accessKeyId</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS access key ID.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>secretAccessKey</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS secret access key.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>sessionToken</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS session token (required for temporary credentials).</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-examples)Resource Configuration Examples

- Basic configuration with default authentication:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: default
    ```
- Configuration with static credentials:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: execute-api
        region: us-east-1
        signingAlgorithm: AWS_SIGV4
        authenticationMode: static
        inlineCredentialProvider:
          accessKeyId: AKIAIOSFODNN7EXAMPLE
          secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    ```
- Configuration with profile authentication:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: profile
        credentialsFileProvider:
          credentialsDataSource:
            filename: ~/.aws/credentials
          profile: my-profile
    ```
- Configuration with SigV4A and unsigned payload:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: "*"
        signingAlgorithm: AWS_SIGV4A
        authenticationMode: default
        useUnsignedPayload: true
    ```
- Configuration with excluded headers:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: default
        matchExcludedHeaders:
          - prefix: x-envoy
          - exact: x-custom-header
          - exact: x-trace-id
    ```

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Service name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The service namespace of the HTTP endpoint. For example: <code>s3</code>, <code>execute-api</code>, or <code>ec2</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Region</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The AWS region string for the service. For SigV4, use a standard region. For example: <code>us-west-2</code>. For SigV4A, use a region set of comma-separated region names (<code>us-west-2</code>), wildcards (<code><strong></strong></code><strong>), or region strings with wildcards (<code>us-east-</code></strong>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Use unsigned payload</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Instead of buffering the request to calculate the payload hash, use the literal string <code>UNSIGNED-PAYLOAD</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signing algorithm</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The signing algorithm to use: <code>AWS_SIGV4</code> or <code>AWS_SIGV4A</code>. <code>AWS_SIGV4A</code> supports multi-region requests.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Match excluded headers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A list of request headers to exclude from signing. Match by any Envoy StringMatcher pattern. For example: <code>prefix: x-envoy</code>, <code>exact: x-custom-header</code>, or <code>exact: x-trace-id</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Authentication mode</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Determines the mode of authentication for AWS credentials. Options: <code>default</code> (uses AWS credential chain: environment variables, AWS credential file, AWS roles), <code>profile</code> (uses a specific profile from the AWS credential file), or <code>static</code> (uses statically configured credentials).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Credentials file provider</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configuration for using credentials from an AWS credential file (required when authentication mode is <code>profile</code>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Credentials file</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Path to the AWS credential file. For example: <code>~/.aws/credentials</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using credentials file provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Profile</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The AWS profile name to use from the credential file.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Inline credential provider</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configuration for statically configured credentials (required when authentication mode is <code>static</code>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Access key ID</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS access key ID when using inline credential provider.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using inline credential provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Secret access key</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS secret access key when using inline credential provider.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using inline credential provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Session token</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS session token when using inline credential provider with temporary credentials.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

<!-- document id=12ff417031c8b98727b187ac5efe6e33d68f1abdfab916462c97b14e2f293b24 url=/mulesoft/current/en-us/gateway/latest/policies-outbound-aws-signature.md -->

# AWS Request Signature Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS Request Signature</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A)</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.11.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-signature-release-notes" class="xref page">AWS Request Signature</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy. Error codes are returned from the upstream service.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The AWS Request Signature policy signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A) authentication. This policy injects the required AWS signature headers into requests to authenticate with AWS services, such as Amazon S3, Amazon API Gateway, or other AWS HTTP endpoints.

The AWS Request Signature policy is an extension of the AWS Request Signing filter native to Envoy. To learn more about the AWS Request Signing filter, see [AWS Request Signing Filter](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/aws_request_signing/v3/aws_request_signing.proto). Not all AWS Request Signing filter parameters are available to the AWS Request Signature policy. To find what parameters are configurable, see [Configuring Policy Parameters](#configuring-policy-parameters).

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

```yaml
- policyRef:
    name: native-aws-signature-flex
  config:
    serviceName: <string> // REQUIRED
    region: <string> // REQUIRED
    useUnsignedPayload: <boolean> // OPTIONAL
    signingAlgorithm: <string> // REQUIRED
    matchExcludedHeaders:
      - <string> // OPTIONAL
    authenticationMode: <string> // REQUIRED
    credentialsFileProvider: <object> // OPTIONAL
    inlineCredentialProvider: <object> // OPTIONAL
```

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">If you don’t configure required parameters, the policy the default value. If the policy doesn’t have a default value, there is a configuration error.</td></tr></tbody></table>

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>serviceName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The service namespace of the HTTP endpoint. For example: <code>s3</code>, <code>execute-api</code>, or <code>ec2</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>region</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The AWS region of the service hosting the HTTP endpoint.<br>
For <code>AWS_SIGV4</code>, this is a standard AWS region. For example: <code>us-west-2</code>.<br>
For <code>AWS_SIGV4A</code>, this is a region set of comma-separated region names (<code>us-west-2</code>), wildcards (<code><strong></strong></code><strong>), or region strings with wildcards (<code>us-east-</code></strong>). A region set enables a signed request to be sent to multiple regions.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>useUnsignedPayload</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Use the literal string <code>UNSIGNED-PAYLOAD</code> to calculate the payload hash instead of buffering the request to calculate the hash. Not all services support this option.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>matchExcludedHeaders</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>A list of request header to exclude from signing. Match by any <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/matcher/v3/string.proto#envoy-v3-api-msg-type-matcher-v3-stringmatcher">Envoy StringMatcher pattern</a>. For example:</p>
</div>
<div class="paragraph">
<p>+</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">matchExcludedHeaders:
  - prefix: x-envoy
  - exact: x-custom-header
  - exact: x-trace-id</code></pre>
</div>
</div>
<div class="paragraph">
<p>+
In the example, the policy does not sign headers that start with <code>x-envoy</code> and the <code>x-custom-header</code> and <code>x-trace-id</code> headers.</p>
</div>
<div class="paragraph">
<p>+
By default, Envoy excludes the <code>x-forwarded-for</code>, <code>x-forwarded-proto</code>, and <code>x-amzn-trace-id</code> headers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>signingAlgorithm</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>AWS_SIGV4</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The signing algorithm to use, either <code>AWS_SIGV4</code> or <code>AWS_SIGV4A</code>. <code>AWS_SIGV4A</code> supports multi-region requests.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>authenticationMode</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>default</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Determines the mode of authentication for AWS credentials. Options are:<br>
* <code>default</code>: Uses the AWS credential chain in the order of environment variables, AWS credential file, then AWS roles.<br>
* <code>profile</code>: Uses a specific profile from the AWS credential file.<br>
* <code>static</code>: Uses statically configured credentials provided in <code>inlineCredentialProvider</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>credentialsFileProvider</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration for using credentials from an AWS credential file. Required when <code>authenticationMode</code> is <code>profile</code>. See <a href="#credential-provider-configuration">Credential Provider Configuration</a> for details.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>inlineCredentialProvider</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration for statically configured credentials. Required when <code>authenticationMode</code> is <code>static</code>. See <a href="#credential-provider-configuration">Credential Provider Configuration</a> for details.</p>
</div></div></td>
</tr>
</tbody>
</table>

### [](#credential-provider-configuration)Credential Provider Configuration

The credential provider configuration depends on the `authenticationMode` setting:

- **`default`**: No additional configuration needed. The policy uses the AWS credential chain (environment variables, AWS credential file, or AWS roles).
- **`profile`**: Use `credentialsFileProvider` to specify the AWS credential file and profile.
- **`static`**: Use `inlineCredentialProvider` to provide credentials directly in the configuration.

#### [](#credentials-file-provider)Credentials File Provider

Use `credentialsFileProvider` when `authenticationMode` is set to `profile`:

```yaml
credentialsFileProvider:
  credentialsDataSource:
    filename: <string> // REQUIRED
  profile: <string> // OPTIONAL
```

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>credentialsDataSource.filename</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Path to the AWS credential file. For example: <code>~/.aws/credentials</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>profile</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>default</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The AWS profile name to use from the credential file.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#inline-credential-provider)Inline Credential Provider

Use `inlineCredentialProvider` when `authenticationMode` is set to `static`:

```yaml
inlineCredentialProvider:
  accessKeyId: <string> // REQUIRED
  secretAccessKey: <string> // REQUIRED
  sessionToken: <string> // OPTIONAL
```

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>accessKeyId</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS access key ID.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>secretAccessKey</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS secret access key.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>sessionToken</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>AWS session token (required for temporary credentials).</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-examples)Resource Configuration Examples

- Basic configuration with default authentication:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: default
    ```
- Configuration with static credentials:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: execute-api
        region: us-east-1
        signingAlgorithm: AWS_SIGV4
        authenticationMode: static
        inlineCredentialProvider:
          accessKeyId: AKIAIOSFODNN7EXAMPLE
          secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    ```
- Configuration with profile authentication:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: profile
        credentialsFileProvider:
          credentialsDataSource:
            filename: ~/.aws/credentials
          profile: my-profile
    ```
- Configuration with SigV4A and unsigned payload:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: "*"
        signingAlgorithm: AWS_SIGV4A
        authenticationMode: default
        useUnsignedPayload: true
    ```
- Configuration with excluded headers:
    
    ```yaml
    - policyRef:
        name: native-aws-signature-flex
      config:
        serviceName: s3
        region: us-west-2
        signingAlgorithm: AWS_SIGV4
        authenticationMode: default
        matchExcludedHeaders:
          - prefix: x-envoy
          - exact: x-custom-header
          - exact: x-trace-id
    ```

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Service name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The service namespace of the HTTP endpoint. For example: <code>s3</code>, <code>execute-api</code>, or <code>ec2</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Region</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The AWS region string for the service. For SigV4, use a standard region. For example: <code>us-west-2</code>. For SigV4A, use a region set of comma-separated region names (<code>us-west-2</code>), wildcards (<code><strong></strong></code><strong>), or region strings with wildcards (<code>us-east-</code></strong>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Use unsigned payload</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Instead of buffering the request to calculate the payload hash, use the literal string <code>UNSIGNED-PAYLOAD</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signing algorithm</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The signing algorithm to use: <code>AWS_SIGV4</code> or <code>AWS_SIGV4A</code>. <code>AWS_SIGV4A</code> supports multi-region requests.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Match excluded headers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A list of request headers to exclude from signing. Match by any Envoy StringMatcher pattern. For example: <code>prefix: x-envoy</code>, <code>exact: x-custom-header</code>, or <code>exact: x-trace-id</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Authentication mode</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Determines the mode of authentication for AWS credentials. Options: <code>default</code> (uses AWS credential chain: environment variables, AWS credential file, AWS roles), <code>profile</code> (uses a specific profile from the AWS credential file), or <code>static</code> (uses statically configured credentials).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Credentials file provider</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configuration for using credentials from an AWS credential file (required when authentication mode is <code>profile</code>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Credentials file</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Path to the AWS credential file. For example: <code>~/.aws/credentials</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using credentials file provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Profile</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The AWS profile name to use from the credential file.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Inline credential provider</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configuration for statically configured credentials (required when authentication mode is <code>static</code>).</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Access key ID</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS access key ID when using inline credential provider.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using inline credential provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Secret access key</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS secret access key when using inline credential provider.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required when using inline credential provider</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Session token</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">AWS session token when using inline credential provider with temporary credentials.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

<!-- document id=3824f9401997c0d62f1feb2377f53e6deb9902a8d55e941c4440f38cb4cde108 url=/mulesoft/current/en-us/gateway/1.13/policies-included-azure-content-safety.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, llm, content safety, azure, guardrails, harm detection
---

# Azure Content Safety Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Azure Content Safety Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates LLM prompts and responses against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/azure-content-safety-release-notes">Azure Content Safety Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates Azure Content Safety policies</p></td></tr><tr><td><p>503 - Service Unavailable: Azure API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The Azure Content Safety policy provides comprehensive content moderation for LLM-based APIs by
evaluating prompts and responses against the Azure AI Content Safety service. The policy integrates
with
[Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)
to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across four categories (**Hate**,
  **SelfHarm**, **Sexual**, and **Violence**) with configurable severity thresholds (`0`, `2`, `4`,
  `6`).

- **Prompt Shield**: Detects jailbreak attempts and indirect prompt-injection attacks using Azure’s
  advanced detection capabilities.

- **Blocklists**: Blocks content matching Azure-managed custom blocklists you define in Azure
  Content Safety Studio.

- **Groundedness Detection**: Evaluates whether LLM responses are grounded in provided reference
  text (hallucination detection for RAG applications).

- **Protected Material Detection**: Detects known copyrighted text in LLM responses.

The policy operates in two independent phases:

- **Request phase**: Moderates user prompts before they reach the upstream LLM, preventing harmful
  or inappropriate prompts from being processed.

- **Response phase**: Moderates LLM responses before they reach the client, ensuring outputs comply
  with safety policies. Streaming responses (`text/event-stream`) aren’t moderated.

When content violates safety policies, the request is rejected with a `403` error code and never
reaches the LLM (request phase) or the client receives a `403` instead of the LLM response (response
phase).

## Before You Begin

Before configuring this policy, you need:

1.  **Azure Account** with access to Azure AI Content Safety

2.  **Azure Content Safety Resource** created in the Azure Portal

3.  **Subscription Key** from the Azure Portal (Keys and Endpoint section)

4.  **Resource Endpoint URL** from the Azure Portal

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Azure Content Safety policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Azure Content Safety Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety endpoint base URL, for example, <code>https://&lt;resource&gt;.cognitiveservices.azure.com</code>.</p></div></div></td></tr><tr><td><div><div><p>Azure API Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety subscription key. The key is passed in the <code>Ocp-Apim-Subscription-Key</code> header.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the user prompt against Azure Content Safety before forwarding to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the LLM response against Azure Content Safety before returning to the client. Rejected responses return <code>403</code> error code. Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr><tr><td><div><div><p>Default Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Severity threshold applied to all four harm categories (Hate, SelfHarm, Sexual, Violence). Content with severity at or above this value is rejected. Supported values are <code>0</code>, <code>2</code> (default), <code>4</code>, and <code>6</code>.</p></div><div><p>For details, see <a href="#severity-thresholds">Severity Thresholds</a>.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>API Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Azure Content Safety API version used for all endpoint calls. Default: <code>2024-09-01</code>.</p></div><div><p>To enable Groundedness Detection, override this to a supported preview version, for example, <code>2024-09-15-preview</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Prompt Shield</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:shieldPrompt</code> alongside <code>text:analyze</code> on the request to detect jailbreak attempts and indirect prompt-injection attacks.</p></div></div></td></tr><tr><td><div><div><p>Hate Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Hate harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>SelfHarm Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the SelfHarm harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Blocklist Names</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Names of Azure-managed blocklists (created in Azure Content Safety Studio) to evaluate against the input text.</p></div></div></td></tr><tr><td><div><div><p>Enable Groundedness Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectGroundedness</code> on the LLM response to detect hallucinated statements. Requires Moderate Response enabled and Grounding Source Selector to be set. Only available in Azure regions that support the API, and only on preview API versions (for example, <code>2024-09-15-preview</code>).</p></div></div></td></tr><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression resolving the grounding source text from the request body. Required when Groundedness Detection is enabled. For example: <code>#[payload.context.documents[0].content]</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Protected Material Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectProtectedMaterial</code> on the LLM response to detect known copyrighted text. Requires Moderate Response enabled.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-request timeout for each Azure Content Safety API call in milliseconds. Must be between 1000 and 30000. Default: <code>5000</code></p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Azure API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The Azure Content Safety policy integrates with Azure AI Content Safety to evaluate LLM prompts and
responses against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the user prompt from the request body.

    2.  The policy sends the prompt to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories (Hate, SelfHarm, Sexual, Violence) and checks
          blocklists

        - `text:shieldPrompt` — Detects jailbreak attempts and indirect injections (when
          `enablePromptShield` is enabled)

    3.  If the prompt violates any policies, the policy blocks the request and returns a `403` error
        code to the client.

    4.  If the prompt passes, the policy forwards the original request to the upstream LLM.

        If grounding source and query selectors are configured, the policy extracts them during
        request processing and stores the values for use in response processing.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the LLM response.

    2.  The policy sends the completion to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories and checks blocklists

        - `text:detectGroundedness` — Scores the response against the grounding source (when enabled
          and grounding source is available)

        - `text:detectProtectedMaterial` — Detects known copyrighted text (when enabled)

    3.  If the response violates any policies, the policy returns a `403` error code to the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation.

### Groundedness Detection

Groundedness detection helps detect hallucinations by evaluating whether LLM responses are grounded
in the provided reference text. This is particularly useful for RAG (Retrieval-Augmented Generation)
applications.

To enable groundedness detection:

1.  Enable groundedness detection in Advanced Configuration (`enableGroundednessDetection: true`).

2.  Configure the **Grounding Source Selector** to extract the reference text from the request body.

3.  Set the API Version to a preview version that supports the groundedness endpoint (for example,
    `2024-09-15-preview`).

The grounding source selector is a DataWeave expression that extracts the reference text the LLM
response should be based on (typically documents or context provided in the request).

Example Configuration

```yaml
advancedConfiguration:
  apiVersion: "2024-09-15-preview"
  enableGroundednessDetection: true
  groundingSourceSelector: "#[payload.context.documents[0].content]"
```

### Severity Thresholds

Azure AI Content Safety evaluates content across four harm categories and assigns a severity level
to each:

- **0** — Safe (no harmful content detected)

- **2** — Low severity

- **4** — Medium severity

- **6** — High severity

The policy rejects content when the severity level is at or above the configured threshold:

<table><colgroup><col> <col></colgroup><thead><tr><th>Threshold Value</th><th>Content Blocked</th></tr></thead><tbody><tr><td><div><div><p>0</p></div></div></td><td><div><div><p>Any flagged content (severity &gt; 0) is blocked. This is the strictest setting.</p></div></div></td></tr><tr><td><div><div><p>2</p></div></div></td><td><div><div><p>Content with low, medium, or high severity is blocked. This is the recommended default.</p></div></div></td></tr><tr><td><div><div><p>4</p></div></div></td><td><div><div><p>Content with medium or high severity is blocked. This allows low-severity content.</p></div></div></td></tr><tr><td><div><div><p>6</p></div></div></td><td><div><div><p>Only high-severity content is blocked. This is the most permissive setting.</p></div></div></td></tr></tbody></table>

You can configure a default threshold that applies to all categories, and optionally override the
threshold for specific categories.

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the prompt or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-reason</code></p></div></div></td><td><div><div><p><code>severity_hate</code>, <code>severity_self_harm</code>, <code>severity_sexual</code>, <code>severity_violence</code>, <code>blocklist</code>, <code>prompt_shield</code>, <code>groundedness</code>, <code>protected_material</code>, <code>service_unavailable</code></p></div></div></td><td><div><div><p>Why the content was rejected. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Response on Reject

When the policy blocks content, it returns a `403` response with this structure:

```json
{
  "error": "Content blocked by Azure Content Safety",
  "categories": ["severity_hate", "blocklist"]
}
```

## Error Handling

### Fail Closed (Default)

When **Fail Open** is disabled (the default), any Azure API error or timeout results in rejection:

- Request phase: HTTP `503` with body `{"error":"Azure Content Safety service unavailable"}`

- Response phase: The response is rewritten to HTTP `503` with the same body

- The `x-llm-proxy-azure-content-safety-reason` header is set to `service_unavailable`

### Fail Open

When **Fail Open** is enabled, Azure API errors are logged but traffic continues unmoderated. The
`x-llm-proxy-azure-content-safety-reason` header is still set to `service_unavailable` for
observability, allowing you to detect partial-coverage moderation in monitoring systems.

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
```

### Strict Threshold with Blocklists

This example blocks any flagged content and applies custom blocklists:

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 0
    advancedConfiguration:
      blocklistNames:
        - competitor-names
        - internal-codenames
```

### Per-Category Thresholds

This example applies different thresholds to different harm categories:

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 2
    advancedConfiguration:
      selfHarmSeverityThreshold: "4" # Allow low-severity SelfHarm discussion
      violenceSeverityThreshold: "0" # Block any flagged Violence
```

### With Groundedness Detection (Hallucination Detection)

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs-eastus.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 4
    advancedConfiguration:
      apiVersion: "2024-09-15-preview"
      enableGroundednessDetection: true
      groundingSourceSelector: "#[payload.context.documents[0].content]"
      enableProtectedMaterialDetection: true
      blocklistNames:
        - my-blocklist
      apiTimeoutMs: 10000
      failOpen: false
```

## See Also

- [Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)

- [Prompt Shield](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/jailbreak-detection)

- [Groundedness Detection](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/groundedness)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies)

<!-- document id=cf462e7cf526a0a09de0af00e3a83574f0a154ad81c2f7990345c16c9b94487d url=/mulesoft/current/en-us/gateway/latest/policies-included-azure-content-safety.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, content safety, azure, guardrails, harm detection
---

# Azure Content Safety Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Azure Content Safety Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates LLM prompts and responses against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/azure-content-safety-release-notes">Azure Content Safety Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates Azure Content Safety policies</p></td></tr><tr><td><p>503 - Service Unavailable: Azure API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The Azure Content Safety policy provides comprehensive content moderation for LLM-based APIs by
evaluating prompts and responses against the Azure AI Content Safety service. The policy integrates
with
[Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)
to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across four categories (**Hate**,
  **SelfHarm**, **Sexual**, and **Violence**) with configurable severity thresholds (`0`, `2`, `4`,
  `6`).

- **Prompt Shield**: Detects jailbreak attempts and indirect prompt-injection attacks using Azure’s
  advanced detection capabilities.

- **Blocklists**: Blocks content matching Azure-managed custom blocklists you define in Azure
  Content Safety Studio.

- **Groundedness Detection**: Evaluates whether LLM responses are grounded in provided reference
  text (hallucination detection for RAG applications).

- **Protected Material Detection**: Detects known copyrighted text in LLM responses.

The policy operates in two independent phases:

- **Request phase**: Moderates user prompts before they reach the upstream LLM, preventing harmful
  or inappropriate prompts from being processed.

- **Response phase**: Moderates LLM responses before they reach the client, ensuring outputs comply
  with safety policies. Streaming responses (`text/event-stream`) aren’t moderated.

When content violates safety policies, the request is rejected with a `403` error code and never
reaches the LLM (request phase) or the client receives a `403` instead of the LLM response (response
phase).

## Before You Begin

Before configuring this policy, you need:

1.  **Azure Account** with access to Azure AI Content Safety

2.  **Azure Content Safety Resource** created in the Azure Portal

3.  **Subscription Key** from the Azure Portal (Keys and Endpoint section)

4.  **Resource Endpoint URL** from the Azure Portal

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Azure Content Safety policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Azure Content Safety Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety endpoint base URL, for example, <code>https://&lt;resource&gt;.cognitiveservices.azure.com</code>.</p></div></div></td></tr><tr><td><div><div><p>Azure API Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety subscription key. The key is passed in the <code>Ocp-Apim-Subscription-Key</code> header.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the user prompt against Azure Content Safety before forwarding to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the LLM response against Azure Content Safety before returning to the client. Rejected responses return <code>403</code> error code. Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr><tr><td><div><div><p>Default Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Severity threshold applied to all four harm categories (Hate, SelfHarm, Sexual, Violence). Content with severity at or above this value is rejected. Supported values are <code>0</code>, <code>2</code> (default), <code>4</code>, and <code>6</code>.</p></div><div><p>For details, see <a href="#severity-thresholds">Severity Thresholds</a>.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>API Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Azure Content Safety API version used for all endpoint calls. Default: <code>2024-09-01</code>.</p></div><div><p>To enable Groundedness Detection, override this to a supported preview version, for example, <code>2024-09-15-preview</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Prompt Shield</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:shieldPrompt</code> alongside <code>text:analyze</code> on the request to detect jailbreak attempts and indirect prompt-injection attacks.</p></div></div></td></tr><tr><td><div><div><p>Hate Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Hate harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>SelfHarm Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the SelfHarm harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Blocklist Names</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Names of Azure-managed blocklists (created in Azure Content Safety Studio) to evaluate against the input text.</p></div></div></td></tr><tr><td><div><div><p>Enable Groundedness Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectGroundedness</code> on the LLM response to detect hallucinated statements. Requires Moderate Response enabled and Grounding Source Selector to be set. Only available in Azure regions that support the API, and only on preview API versions (for example, <code>2024-09-15-preview</code>).</p></div></div></td></tr><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression resolving the grounding source text from the request body. Required when Groundedness Detection is enabled. For example: <code>#[payload.context.documents[0].content]</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Protected Material Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectProtectedMaterial</code> on the LLM response to detect known copyrighted text. Requires Moderate Response enabled.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-request timeout for each Azure Content Safety API call in milliseconds. Must be between 1000 and 30000. Default: <code>5000</code></p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Azure API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The Azure Content Safety policy integrates with Azure AI Content Safety to evaluate LLM prompts and
responses against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the user prompt from the request body.

    2.  The policy sends the prompt to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories (Hate, SelfHarm, Sexual, Violence) and checks
          blocklists

        - `text:shieldPrompt` — Detects jailbreak attempts and indirect injections (when
          `enablePromptShield` is enabled)

    3.  If the prompt violates any policies, the policy blocks the request and returns a `403` error
        code to the client.

    4.  If the prompt passes, the policy forwards the original request to the upstream LLM.

        If grounding source and query selectors are configured, the policy extracts them during
        request processing and stores the values for use in response processing.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the LLM response.

    2.  The policy sends the completion to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories and checks blocklists

        - `text:detectGroundedness` — Scores the response against the grounding source (when enabled
          and grounding source is available)

        - `text:detectProtectedMaterial` — Detects known copyrighted text (when enabled)

    3.  If the response violates any policies, the policy returns a `403` error code to the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation.

### Groundedness Detection

Groundedness detection helps detect hallucinations by evaluating whether LLM responses are grounded
in the provided reference text. This is particularly useful for RAG (Retrieval-Augmented Generation)
applications.

To enable groundedness detection:

1.  Enable groundedness detection in Advanced Configuration (`enableGroundednessDetection: true`).

2.  Configure the **Grounding Source Selector** to extract the reference text from the request body.

3.  Set the API Version to a preview version that supports the groundedness endpoint (for example,
    `2024-09-15-preview`).

The grounding source selector is a DataWeave expression that extracts the reference text the LLM
response should be based on (typically documents or context provided in the request).

Example Configuration

```yaml
advancedConfiguration:
  apiVersion: "2024-09-15-preview"
  enableGroundednessDetection: true
  groundingSourceSelector: "#[payload.context.documents[0].content]"
```

### Severity Thresholds

Azure AI Content Safety evaluates content across four harm categories and assigns a severity level
to each:

- **0** — Safe (no harmful content detected)

- **2** — Low severity

- **4** — Medium severity

- **6** — High severity

The policy rejects content when the severity level is at or above the configured threshold:

<table><colgroup><col> <col></colgroup><thead><tr><th>Threshold Value</th><th>Content Blocked</th></tr></thead><tbody><tr><td><div><div><p>0</p></div></div></td><td><div><div><p>Any flagged content (severity &gt; 0) is blocked. This is the strictest setting.</p></div></div></td></tr><tr><td><div><div><p>2</p></div></div></td><td><div><div><p>Content with low, medium, or high severity is blocked. This is the recommended default.</p></div></div></td></tr><tr><td><div><div><p>4</p></div></div></td><td><div><div><p>Content with medium or high severity is blocked. This allows low-severity content.</p></div></div></td></tr><tr><td><div><div><p>6</p></div></div></td><td><div><div><p>Only high-severity content is blocked. This is the most permissive setting.</p></div></div></td></tr></tbody></table>

You can configure a default threshold that applies to all categories, and optionally override the
threshold for specific categories.

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the prompt or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-reason</code></p></div></div></td><td><div><div><p><code>severity_hate</code>, <code>severity_self_harm</code>, <code>severity_sexual</code>, <code>severity_violence</code>, <code>blocklist</code>, <code>prompt_shield</code>, <code>groundedness</code>, <code>protected_material</code>, <code>service_unavailable</code></p></div></div></td><td><div><div><p>Why the content was rejected. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Response on Reject

When the policy blocks content, it returns a `403` response with this structure:

```json
{
  "error": "Content blocked by Azure Content Safety",
  "categories": ["severity_hate", "blocklist"]
}
```

## Error Handling

### Fail Closed (Default)

When **Fail Open** is disabled (the default), any Azure API error or timeout results in rejection:

- Request phase: HTTP `503` with body `{"error":"Azure Content Safety service unavailable"}`

- Response phase: The response is rewritten to HTTP `503` with the same body

- The `x-llm-proxy-azure-content-safety-reason` header is set to `service_unavailable`

### Fail Open

When **Fail Open** is enabled, Azure API errors are logged but traffic continues unmoderated. The
`x-llm-proxy-azure-content-safety-reason` header is still set to `service_unavailable` for
observability, allowing you to detect partial-coverage moderation in monitoring systems.

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
```

### Strict Threshold with Blocklists

This example blocks any flagged content and applies custom blocklists:

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 0
    advancedConfiguration:
      blocklistNames:
        - competitor-names
        - internal-codenames
```

### Per-Category Thresholds

This example applies different thresholds to different harm categories:

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 2
    advancedConfiguration:
      selfHarmSeverityThreshold: "4" # Allow low-severity SelfHarm discussion
      violenceSeverityThreshold: "0" # Block any flagged Violence
```

### With Groundedness Detection (Hallucination Detection)

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs-eastus.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 4
    advancedConfiguration:
      apiVersion: "2024-09-15-preview"
      enableGroundednessDetection: true
      groundingSourceSelector: "#[payload.context.documents[0].content]"
      enableProtectedMaterialDetection: true
      blocklistNames:
        - my-blocklist
      apiTimeoutMs: 10000
      failOpen: false
```

## See Also

- [Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)

- [Prompt Shield](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/jailbreak-detection)

- [Groundedness Detection](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/groundedness)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies)

<!-- document id=8dc21e23f7bd7045492e9badea43e1e66497bec78afa4461fd85483ebd41222f url=/mulesoft/current/en-us/gateway/1.12/policies-included-basic-auth-ldap.md -->

---
product: Omni Gateway
version: 1.12
keywords: basic authentication, ldap, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: LDAP Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: LDAP</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.1.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr></tbody></table>

## Summary

The Lightweight Directory Access Protocol (LDAP) authentication policy specifies how to restrict
access to an API using LDAP authentication mechanism.

When an error is encountered, the Basic Authentication - LDAP policy returns an "WWW-Authenticate"
HTTP header field using the format:\`WWW-Authenticate: Basic realm="mule-realm"\`.

LDAP is an inverted tree, and each leaf has a username-password pair and associated metadata. Each
level is like a tree branch. For more information about LDAP, see
[About LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol).

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ldap-authentication-flex config: ldapServerURL: <string> // OPTIONAL, default:
"ldap://127.0.0.1:389" authorizationOrigin: <string> // OPTIONAL, default:
"httpBasicAuthenticationHeader" authorizationExpression: <string> // REQUIRED when
authorizationOrigin is "customExpression" ldapServerUserDn: <string> // REQUIRED
ldapServerUserPassword: <string> // REQUIRED ldapSearchBase: <string> // REQUIRED ldapSearchFilter:
<string> // OPTIONAL, default: "(uid={0})" ldapSearchInSubtree: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ldapServerURL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>ldap://127.0.0.1:389</code></p></div></div></td><td><div><div><p>Address and port of the location to the LDAP server</p></div></div></td></tr><tr><td><div><div><p><code>authorizationOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>httpBasicAuthenticationHeader</code></p></div></div></td><td><div><div><p>Origin of the Authorization token. Use <code>httpBasicAuthenticationHeader</code> to read credentials from the HTTP Basic Authentication header, or <code>customExpression</code> to extract the token using a DataWeave expression.</p></div></div></td></tr><tr><td><div><div><p><code>authorizationExpression</code></p></div></div></td><td><div><div><p>Required when <code>authorizationOrigin</code> is <code>customExpression</code></p></div></div></td><td><div><div><p><code>#[attributes.headers['token']]</code></p></div></div></td><td><div><div><p>DataWeave expression to extract the Authorization token from API requests. Only applicable when <code>authorizationOrigin</code> is <code>customExpression</code>.</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserDn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserPassword</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The password for the user or usergroup</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchBase</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The place where the LDAP search begins</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchFilter</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchInSubtree</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Whether to examine the subtree below the base DN and include the base DN level. Performance will be affected by this. Otherwise, the one-level scope will be used, examining only the level immediately below the base DN</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ldap-authentication-flex config: ldapServerURL: "ldap://localhost:389"
authorizationOrigin: "httpBasicAuthenticationHeader" authorizationExpression:
"#\[attributes.headers\['Authorization'\]\]" ldapServerUserDn: "cn=admin,dc=example,dc=org"
ldapServerUserPassword: "admin" ldapSearchBase: "dc=example,dc=org" ldapSearchFilter: "(uid={0})"
ldapSearchInSubtree: true

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>The URL of your LDAP OR LDAPS server, including the port number.</p></div></div></td></tr><tr><td><div><div><p>Authorization token origin</p></div></div></td><td><div><div><p>Origin of the Authorization token: <strong>HTTP Basic Authentication Header</strong> or <strong>Custom Expression</strong>.</p></div></div></td></tr><tr><td><div><div><p>Token Expression</p></div></div></td><td><div><div><p>DataWeave expression used to extract the Authorization from API requests. Shown when Authorization token origin is <strong>Custom Expression</strong>.</p></div></div></td></tr><tr><td><div><div><p>LDAP User DN</p></div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP.</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>The starting point for the search in the directory tree.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.</p></div></div></td></tr></tbody></table>

> [!NOTE] All parameters are required to successfully configure LDAP or Active Directory.

## Example Configuration for an Active Directory

You can configure Active Directory for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>CN=Administrator,CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(sAMAccountName={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to Active Directory applications.

## Example Configuration for OpenLDAP

You can configure OpenLDAP for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>cn=Manager,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>ou=people,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(uid={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to OpenLDAP applications.

## How This Policy Works

The Basic Authentication - LDAP policy intercepts the request to the protected resource and looks
for the `Authorization` HTTP header.

The policy then extracts the username and password encoded in Base64 and then requests the
configured LDAP instance to determine if the user credentials are correct in the provided LDAP
context.

You can configure the Basic Authentication: LDAP policy to credentials using the following methods:

- Search for the valid username and password pair in the level specified.

- Search for the valid username and password pair in the level specified, including lower levels.
  This search option is comprehensive, however, can result in slow performance.

### Search Scope

Your search scope options differ depending on your policy version. The search scope options are one
level for LDAP 1.0.0 and two levels (subtree) for LDAP 1.1.0.

You can choose between `one level` and `subtree` search scopes by using the `LDAP Search in subtree`
option.

The `LDAP search base` is the starting point for the search in the directory.

### One-Level Search Scope

With this option, the filter affects only the objects immediately subordinate to the
`LDAP search base`, and not the `LDAP search base` itself.

In the following example, the first level has four entries: two users and two groups. These are the
only entries that are a part of any search:

![Diagram of a hierarchical organizational structure](/mulesoft/current/en-us/gateway/1.12/_images/search-scope.png)

If you set the search filter to `(uid={0})`, only `Jane` and `Paul` are found. The group entries are
not considered.

#### Subtree Search Scope

With this option, the Basic Authentication - LDAP policy examines the subtree below the
`LDAP search base` and also includes the `LDAP search base` level. Notice that performance is
affected by this behavior.

In the previous example, the analyzed area covers the entire organization. The group and user
entries are considered at any level of the organization:

![A flowchart that shows an example organizational structure](/mulesoft/current/en-us/gateway/1.12/_images/search-scope2.png)

## Creating Requests for APIs with Basic Authentication Policies Applied

After applying the Basic Authentication - LDAP policy to the API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a Base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

From the `username` and search filter, LDAP finds the registered user and then verifies credentials.
The valid result is returned:

![Here’s a sequence diagram that illustrates the message flow for client authentication through an LDAP Server](/mulesoft/current/en-us/gateway/1.12/_images/ldap-verification.png)

The following diagram illustrates an invalid request:

![A sequence diagram that illustrates the message flow for authorization](/mulesoft/current/en-us/gateway/1.12/_images/ldap-verification-invalid.png)

The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the
authorization header is malformed, not provided, or invalid.

<!-- document id=fefe2d2bb77734b6696af4795e1d52783a5eade042f8faec0bf309e11c3de139 url=/mulesoft/current/en-us/gateway/1.13/policies-included-basic-auth-ldap.md -->

---
product: Omni Gateway
version: 1.13
keywords: basic authentication, ldap, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: LDAP Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: LDAP</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.1.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-ldap-release-notes">Basic Authentication: LDAP</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr></tbody></table>

## Summary

The Lightweight Directory Access Protocol (LDAP) authentication policy specifies how to restrict
access to an API using LDAP authentication mechanism.

When an error is encountered, the Basic Authentication - LDAP policy returns an "WWW-Authenticate"
HTTP header field using the format:\`WWW-Authenticate: Basic realm="mule-realm"\`.

LDAP is an inverted tree, and each leaf has a username-password pair and associated metadata. Each
level is like a tree branch. For more information about LDAP, see
[About LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ldap-authentication-flex config: ldapServerURL: <string> // OPTIONAL, default:
"ldap://127.0.0.1:389" authorizationOrigin: <string> // OPTIONAL, default:
"httpBasicAuthenticationHeader" authorizationExpression: <string> // REQUIRED when
authorizationOrigin is "customExpression" ldapServerUserDn: <string> // REQUIRED
ldapServerUserPassword: <string> // REQUIRED ldapSearchBase: <string> // REQUIRED ldapSearchFilter:
<string> // OPTIONAL, default: "(uid={0})" ldapSearchInSubtree: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ldapServerURL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>ldap://127.0.0.1:389</code></p></div></div></td><td><div><div><p>Address and port of the location to the LDAP server</p></div></div></td></tr><tr><td><div><div><p><code>authorizationOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>httpBasicAuthenticationHeader</code></p></div></div></td><td><div><div><p>Origin of the Authorization token. Use <code>httpBasicAuthenticationHeader</code> to read credentials from the HTTP Basic Authentication header, or <code>customExpression</code> to extract the token using a DataWeave expression.</p></div></div></td></tr><tr><td><div><div><p><code>authorizationExpression</code></p></div></div></td><td><div><div><p>Required when <code>authorizationOrigin</code> is <code>customExpression</code></p></div></div></td><td><div><div><p><code>#[attributes.headers['token']]</code></p></div></div></td><td><div><div><p>DataWeave expression to extract the Authorization token from API requests. Only applicable when <code>authorizationOrigin</code> is <code>customExpression</code>.</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserDn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserPassword</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The password for the user or usergroup</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchBase</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The place where the LDAP search begins</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchFilter</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchInSubtree</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Whether to examine the subtree below the base DN and include the base DN level. Performance will be affected by this. Otherwise, the one-level scope will be used, examining only the level immediately below the base DN</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ldap-authentication-flex config: ldapServerURL: "ldap://localhost:389"
authorizationOrigin: "httpBasicAuthenticationHeader" authorizationExpression:
"#\[attributes.headers\['Authorization'\]\]" ldapServerUserDn: "cn=admin,dc=example,dc=org"
ldapServerUserPassword: "admin" ldapSearchBase: "dc=example,dc=org" ldapSearchFilter: "(uid={0})"
ldapSearchInSubtree: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>The URL of your LDAP OR LDAPS server, including the port number.</p></div></div></td></tr><tr><td><div><div><p>Authorization token origin</p></div></div></td><td><div><div><p>Origin of the Authorization token: <strong>HTTP Basic Authentication Header</strong> or <strong>Custom Expression</strong>.</p></div></div></td></tr><tr><td><div><div><p>Token Expression</p></div></div></td><td><div><div><p>DataWeave expression used to extract the Authorization from API requests. Shown when Authorization token origin is <strong>Custom Expression</strong>.</p></div></div></td></tr><tr><td><div><div><p>LDAP User DN</p></div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP.</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>The starting point for the search in the directory tree.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.</p></div></div></td></tr></tbody></table>

> [!NOTE] All parameters are required to successfully configure LDAP or Active Directory.

## Example Configuration for an Active Directory

You can configure Active Directory for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>CN=Administrator,CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(sAMAccountName={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to Active Directory applications.

## Example Configuration for OpenLDAP

You can configure OpenLDAP for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>cn=Manager,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>ou=people,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(uid={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to OpenLDAP applications.

## How This Policy Works

The Basic Authentication - LDAP policy intercepts the request to the protected resource and looks
for the `Authorization` HTTP header.

The policy then extracts the username and password encoded in Base64 and then requests the
configured LDAP instance to determine if the user credentials are correct in the provided LDAP
context.

You can configure the Basic Authentication: LDAP policy to credentials using the following methods:

- Search for the valid username and password pair in the level specified.

- Search for the valid username and password pair in the level specified, including lower levels.
  This search option is comprehensive, however, can result in slow performance.

### Search Scope

Your search scope options differ depending on your policy version. The search scope options are one
level for LDAP 1.0.0 and two levels (subtree) for LDAP 1.1.0.

You can choose between `one level` and `subtree` search scopes by using the `LDAP Search in subtree`
option.

The `LDAP search base` is the starting point for the search in the directory.

### One-Level Search Scope

With this option, the filter affects only the objects immediately subordinate to the
`LDAP search base`, and not the `LDAP search base` itself.

In the following example, the first level has four entries: two users and two groups. These are the
only entries that are a part of any search:

![Diagram of a hierarchical organizational structure](/mulesoft/current/en-us/gateway/1.13/_images/search-scope.png)

If you set the search filter to `(uid={0})`, only `Jane` and `Paul` are found. The group entries are
not considered.

#### Subtree Search Scope

With this option, the Basic Authentication - LDAP policy examines the subtree below the
`LDAP search base` and also includes the `LDAP search base` level. Notice that performance is
affected by this behavior.

In the previous example, the analyzed area covers the entire organization. The group and user
entries are considered at any level of the organization:

![A flowchart that shows an example organizational structure](/mulesoft/current/en-us/gateway/1.13/_images/search-scope2.png)

## Creating Requests for APIs with Basic Authentication Policies Applied

After applying the Basic Authentication - LDAP policy to the API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a Base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

From the `username` and search filter, LDAP finds the registered user and then verifies credentials.
The valid result is returned:

![Here’s a sequence diagram that illustrates the message flow for client authentication through an LDAP Server](/mulesoft/current/en-us/gateway/1.13/_images/ldap-verification.png)

The following diagram illustrates an invalid request:

![A sequence diagram that illustrates the message flow for authorization](/mulesoft/current/en-us/gateway/1.13/_images/ldap-verification-invalid.png)

The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the
authorization header is malformed, not provided, or invalid.

<!-- document id=1f036314d90cb4601c7c482a0436d96d82370f13efffa5a0650d4941a65575ec url=/mulesoft/current/en-us/gateway/1.9/policies-included-basic-auth-ldap.md -->

---
product: Omni Gateway
version: 1.9
keywords: basic authentication, ldap, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: LDAP Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: LDAP</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.1.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr></tbody></table>

## Summary

The Lightweight Directory Access Protocol (LDAP) authentication policy specifies how to restrict
access to an API using LDAP authentication mechanism.

When an error is encountered, the Basic Authentication - LDAP policy returns an "WWW-Authenticate"
HTTP header field using the format:\`WWW-Authenticate: Basic realm="mule-realm"\`.

LDAP is an inverted tree, and each leaf has a username-password pair and associated metadata. Each
level is like a tree branch. For more information about LDAP, see
[About LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol).

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: ldap-authentication-flex config: ldapServerURL: <string> // OPTIONAL, default:
"ldap://127.0.0.1:389" ldapServerUserDn: <string> // REQUIRED ldapServerUserPassword: <string> //
REQUIRED ldapSearchBase: <string> // REQUIRED ldapSearchFilter: <string> // OPTIONAL, default:
"(uid={0})" ldapSearchInSubtree: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ldapServerURL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>ldap://127.0.0.1:389</code></p></div></div></td><td><div><div><p>Address and port of the location to the LDAP server</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserDn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserPassword</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The password for the user or usergroup</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchBase</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The place where the LDAP search begins</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchFilter</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchInSubtree</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Whether to examine the subtree below the base DN and include the base DN level. Performance will be affected by this. Otherwise, the one-level scope will be used, examining only the level immediately below the base DN</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ldap-authentication-flex config: dapServerURL: "ldap://localhost:369"
ldapServerUserDn: "cn=admin,dc=example,dc=org" ldapServerUserPassword: "admin" ldapSearchBase:
"dc=example,dc=org" ldapSearchFilter: "(uid={0})" ldapSearchInSubtree: true

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>The URL of your LDAP OR LDAPS server, including the port number.</p></div></div></td></tr><tr><td><div><div><p>LDAP User DN</p></div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP.</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>The starting point for the search in the directory tree.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.</p></div></div></td></tr></tbody></table>

> [!NOTE] All parameters are required to successfully configure LDAP or Active Directory.

## Example Configuration for an Active Directory

You can configure Active Directory for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>CN=Administrator,CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(sAMAccountName={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to Active Directory applications.

## Example Configuration for OpenLDAP

You can configure OpenLDAP for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>cn=Manager,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>ou=people,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(uid={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to OpenLDAP applications.

## How This Policy Works

The Basic Authentication - LDAP policy intercepts the request to the protected resource and looks
for the `Authorization` HTTP header.

The policy then extracts the username and password encoded in Base64 and then requests the
configured LDAP instance to determine if the user credentials are correct in the provided LDAP
context.

You can configure the Basic Authentication: LDAP policy to credentials using the following methods:

- Search for the valid username and password pair in the level specified.

- Search for the valid username and password pair in the level specified, including lower levels.
  This search option is comprehensive, however, can result in slow performance.

### Search Scope

Your search scope options differ depending on your policy version. The search scope options are one
level for LDAP 1.0.0 and two levels (subtree) for LDAP 1.1.0.

You can choose between `one level` and `subtree` search scopes by using the `LDAP Search in subtree`
option.

The `LDAP search base` is the starting point for the search in the directory.

### One-Level Search Scope

With this option, the filter affects only the objects immediately subordinate to the
`LDAP search base`, and not the `LDAP search base` itself.

In the following example, the first level has four entries: two users and two groups. These are the
only entries that are a part of any search:

![Diagram of a hierarchical organizational structure](/mulesoft/current/en-us/gateway/1.9/_images/search-scope.png)

If you set the search filter to `(uid={0})`, only `Jane` and `Paul` are found. The group entries are
not considered.

#### Subtree Search Scope

With this option, the Basic Authentication - LDAP policy examines the subtree below the
`LDAP search base` and also includes the `LDAP search base` level. Notice that performance is
affected by this behavior.

In the previous example, the analyzed area covers the entire organization. The group and user
entries are considered at any level of the organization:

![A flowchart that shows an example organizational structure](/mulesoft/current/en-us/gateway/1.9/_images/search-scope2.png)

## Creating Requests for APIs with Basic Authentication Policies Applied

After applying the Basic Authentication - LDAP policy to the API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a Base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

From the `username` and search filter, LDAP finds the registered user and then verifies credentials.
The valid result is returned:

![Here’s a sequence diagram that illustrates the message flow for client authentication through an LDAP Server](/mulesoft/current/en-us/gateway/1.9/_images/ldap-verification.png)

The following diagram illustrates an invalid request:

![A sequence diagram that illustrates the message flow for authorization](/mulesoft/current/en-us/gateway/1.9/_images/ldap-verification-invalid.png)

The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the
authorization header is malformed, not provided, or invalid.

<!-- document id=e96f14aa235c3cb6b499239b36172b7446b6b0ccbb6c403fd96ecbda4bf08b30 url=/mulesoft/current/en-us/gateway/latest/policies-included-basic-auth-ldap.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: basic authentication, ldap, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: LDAP Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: LDAP</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.1.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-ldap-release-notes">Basic Authentication: LDAP</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr></tbody></table>

## Summary

The Lightweight Directory Access Protocol (LDAP) authentication policy specifies how to restrict
access to an API using LDAP authentication mechanism.

When an error is encountered, the Basic Authentication - LDAP policy returns an "WWW-Authenticate"
HTTP header field using the format:\`WWW-Authenticate: Basic realm="mule-realm"\`.

LDAP is an inverted tree, and each leaf has a username-password pair and associated metadata. Each
level is like a tree branch. For more information about LDAP, see
[About LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ldap-authentication-flex config: ldapServerURL: <string> // OPTIONAL, default:
"ldap://127.0.0.1:389" authorizationOrigin: <string> // OPTIONAL, default:
"httpBasicAuthenticationHeader" authorizationExpression: <string> // REQUIRED when
authorizationOrigin is "customExpression" ldapServerUserDn: <string> // REQUIRED
ldapServerUserPassword: <string> // REQUIRED ldapSearchBase: <string> // REQUIRED ldapSearchFilter:
<string> // OPTIONAL, default: "(uid={0})" ldapSearchInSubtree: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ldapServerURL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>ldap://127.0.0.1:389</code></p></div></div></td><td><div><div><p>Address and port of the location to the LDAP server</p></div></div></td></tr><tr><td><div><div><p><code>authorizationOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>httpBasicAuthenticationHeader</code></p></div></div></td><td><div><div><p>Origin of the Authorization token. Use <code>httpBasicAuthenticationHeader</code> to read credentials from the HTTP Basic Authentication header, or <code>customExpression</code> to extract the token using a DataWeave expression.</p></div></div></td></tr><tr><td><div><div><p><code>authorizationExpression</code></p></div></div></td><td><div><div><p>Required when <code>authorizationOrigin</code> is <code>customExpression</code></p></div></div></td><td><div><div><p><code>#[attributes.headers['token']]</code></p></div></div></td><td><div><div><p>DataWeave expression to extract the Authorization token from API requests. Only applicable when <code>authorizationOrigin</code> is <code>customExpression</code>.</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserDn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserPassword</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The password for the user or usergroup</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchBase</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The place where the LDAP search begins</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchFilter</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchInSubtree</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Whether to examine the subtree below the base DN and include the base DN level. Performance will be affected by this. Otherwise, the one-level scope will be used, examining only the level immediately below the base DN</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ldap-authentication-flex config: ldapServerURL: "ldap://localhost:389"
authorizationOrigin: "httpBasicAuthenticationHeader" authorizationExpression:
"#\[attributes.headers\['Authorization'\]\]" ldapServerUserDn: "cn=admin,dc=example,dc=org"
ldapServerUserPassword: "admin" ldapSearchBase: "dc=example,dc=org" ldapSearchFilter: "(uid={0})"
ldapSearchInSubtree: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>The URL of your LDAP OR LDAPS server, including the port number.</p></div></div></td></tr><tr><td><div><div><p>Authorization token origin</p></div></div></td><td><div><div><p>Origin of the Authorization token: <strong>HTTP Basic Authentication Header</strong> or <strong>Custom Expression</strong>.</p></div></div></td></tr><tr><td><div><div><p>Token Expression</p></div></div></td><td><div><div><p>DataWeave expression used to extract the Authorization from API requests. Shown when Authorization token origin is <strong>Custom Expression</strong>.</p></div></div></td></tr><tr><td><div><div><p>LDAP User DN</p></div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP.</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>The starting point for the search in the directory tree.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.</p></div></div></td></tr></tbody></table>

> [!NOTE] All parameters are required to successfully configure LDAP or Active Directory.

## Example Configuration for an Active Directory

You can configure Active Directory for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>CN=Administrator,CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(sAMAccountName={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to Active Directory applications.

## Example Configuration for OpenLDAP

You can configure OpenLDAP for your LDAP authentication by providing the following values:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>cn=Manager,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>ou=people,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(uid={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

The search filter string in the example is specific to OpenLDAP applications.

## How This Policy Works

The Basic Authentication - LDAP policy intercepts the request to the protected resource and looks
for the `Authorization` HTTP header.

The policy then extracts the username and password encoded in Base64 and then requests the
configured LDAP instance to determine if the user credentials are correct in the provided LDAP
context.

You can configure the Basic Authentication: LDAP policy to credentials using the following methods:

- Search for the valid username and password pair in the level specified.

- Search for the valid username and password pair in the level specified, including lower levels.
  This search option is comprehensive, however, can result in slow performance.

### Search Scope

Your search scope options differ depending on your policy version. The search scope options are one
level for LDAP 1.0.0 and two levels (subtree) for LDAP 1.1.0.

You can choose between `one level` and `subtree` search scopes by using the `LDAP Search in subtree`
option.

The `LDAP search base` is the starting point for the search in the directory.

### One-Level Search Scope

With this option, the filter affects only the objects immediately subordinate to the
`LDAP search base`, and not the `LDAP search base` itself.

In the following example, the first level has four entries: two users and two groups. These are the
only entries that are a part of any search:

![Diagram of a hierarchical organizational structure](/mulesoft/current/en-us/gateway/latest/_images/search-scope.png)

If you set the search filter to `(uid={0})`, only `Jane` and `Paul` are found. The group entries are
not considered.

#### Subtree Search Scope

With this option, the Basic Authentication - LDAP policy examines the subtree below the
`LDAP search base` and also includes the `LDAP search base` level. Notice that performance is
affected by this behavior.

In the previous example, the analyzed area covers the entire organization. The group and user
entries are considered at any level of the organization:

![A flowchart that shows an example organizational structure](/mulesoft/current/en-us/gateway/latest/_images/search-scope2.png)

## Creating Requests for APIs with Basic Authentication Policies Applied

After applying the Basic Authentication - LDAP policy to the API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a Base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

From the `username` and search filter, LDAP finds the registered user and then verifies credentials.
The valid result is returned:

![Here’s a sequence diagram that illustrates the message flow for client authentication through an LDAP Server](/mulesoft/current/en-us/gateway/latest/_images/ldap-verification.png)

The following diagram illustrates an invalid request:

![A sequence diagram that illustrates the message flow for authorization](/mulesoft/current/en-us/gateway/latest/_images/ldap-verification-invalid.png)

The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the
authorization header is malformed, not provided, or invalid.

<!-- document id=f9f7fe5d6484f431960368af579a0cf2fa6660f5702e675ae6c494d3007d34d7 url=/mulesoft/current/en-us/gateway/1.12/policies-included-basic-auth-simple.md -->

---
product: Omni Gateway
version: 1.12
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: Simple Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: Simple</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.2</p></td></tr><tr><td></td><td><p>401 - Unauthorized or invalid client application credentials in HTTP or RAML APIs</p></td></tr><tr><td></td><td><p>500 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.1</p></td></tr></tbody></table>

## Summary

The Basic Authentication: Simple policy protects an API by forcing applications to provide a
username and password when making requests.

The policy follows [basic HTTP authentication standards](https://tools.ietf.org/html/rfc7617).

When an error is encountered, the policy returns an "WWW-Authenticate" HTTP header field.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: http-basic-authentication-flex config: username: <string> // REQUIRED password:
<string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Flex Gateway Connected Mode

When you apply the Basic Authentication: Simple policy to an API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

<!-- document id=dcfa5e0bd0be52746b29c78cc2851cd6792062ec07e6459a201f28954fa41dc9 url=/mulesoft/current/en-us/gateway/1.13/policies-included-basic-auth-simple.md -->

---
product: Omni Gateway
version: 1.13
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: Simple Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: Simple</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-simple-release-notes">Basic Authentication: Simple</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.2</p></td></tr><tr><td></td><td><p>401 - Unauthorized or invalid client application credentials in HTTP or RAML APIs</p></td></tr><tr><td></td><td><p>500 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.1</p></td></tr></tbody></table>

## Summary

The Basic Authentication: Simple policy protects an API by forcing applications to provide a
username and password when making requests.

The policy follows [basic HTTP authentication standards](https://tools.ietf.org/html/rfc7617).

When an error is encountered, the policy returns an "WWW-Authenticate" HTTP header field.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: http-basic-authentication-flex config: username: <string> // REQUIRED password:
<string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Omni Gateway Connected Mode

When you apply the Basic Authentication: Simple policy to an API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

<!-- document id=76da7f530c1bfba1dbd25ce4f4910e5188105087c03a223ac6d8942c4b205870 url=/mulesoft/current/en-us/gateway/1.9/policies-included-basic-auth-simple.md -->

---
product: Omni Gateway
version: 1.9
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: Simple Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: Simple</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.2</p></td></tr><tr><td></td><td><p>401 - Unauthorized or invalid client application credentials in HTTP or RAML APIs</p></td></tr><tr><td></td><td><p>500 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.1</p></td></tr></tbody></table>

## Summary

The Basic Authentication: Simple policy protects an API by forcing applications to provide a
username and password when making requests.

The policy follows
[basic HTTP authentication standards](https://datatracker.ietf.org/doc/html/rfc7617).

When an error is encountered, the policy returns an "WWW-Authenticate" HTTP header field.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: http-basic-authentication-flex config: username: <string> // REQUIRED password:
<string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Flex Gateway Connected Mode

When you apply the Basic Authentication: Simple policy to an API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

<!-- document id=701817698cd5ba463be4dadec53edfadc85dc0fda2b78c294f9fc84ae5389132 url=/mulesoft/current/en-us/gateway/latest/policies-included-basic-auth-simple.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: Simple Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: Simple</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-simple-release-notes">Basic Authentication: Simple</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.2</p></td></tr><tr><td></td><td><p>401 - Unauthorized or invalid client application credentials in HTTP or RAML APIs</p></td></tr><tr><td></td><td><p>500 - Unauthorized or invalid client application credentials in WSDL API using SOAP 1.1</p></td></tr></tbody></table>

## Summary

The Basic Authentication: Simple policy protects an API by forcing applications to provide a
username and password when making requests.

The policy follows [basic HTTP authentication standards](https://tools.ietf.org/html/rfc7617).

When an error is encountered, the policy returns an "WWW-Authenticate" HTTP header field.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: http-basic-authentication-flex config: username: <string> // REQUIRED password:
<string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A base-64 encoded string</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Omni Gateway Connected Mode

When you apply the Basic Authentication: Simple policy to an API, a request to that API must contain
the following header:

Authorization: Basic <username:password>

The `username:password` value must be a base64-encoded string. For example on a Mac OS X or Linux
system, the username and password requirement is implemented as:

`echo -n '<Client Id>:<Client Secret>' | base64`

<!-- document id=3e270adb7b2206b08bbf7c5f83390a471661bc0099f2999573e1d60deaee44da url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.12
---

# Circuit Breaker Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Circuit Breaker</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Prevents an upstream from receiving too many requests or connections</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>503 - Service Unavailable</p></div></div></td></tr></tbody></table>

## Summary

The Circuit Breaker policy prevents upstream services from receiving too many requests or
connections at a time. If the defined maximums are reached, Flex Gateway returns a
`503 - Service Unavailable` error.

For Managed Flex Gateways or Connected Mode, each API instance has its own independent limit when
requesting the same upstream, allowing each to use the full maximum. In Local Mode, the limits are
shared among different API instances, so they must all adhere to the same upstream maximum. For all
modes, maximums are not distributed across replicas; each Gateway can use the full maximum.

The Circuit Breaker policy is an extension of the Envoy upstream clusters circuit breaking feature.
To learn more about the Envoy’s circuit breaking, see
[Circuit Breaking](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html)
in the Envoy documentation.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: upstream-policy spec:
targetRef: Kind: Service name: upstream policyRef: name: circuit-breaker-flex config: thresholds:
maxConnections: <number> // OPTIONAL maxPendingRequests: <number> // OPTIONAL maxRequests: <number>
// OPTIONAL maxRetries: <number> // OPTIONAL maxConnectionPools: <number> // OPTIONAL

> [!NOTE] For Local Mode, the limits are not independent, so different API instances share the
> maximums for an upstream.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumConnections</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumPendingRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRetries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p><code>maximumConnectionPools</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example defines a policy that supports a maximum of one request at a time:

apiVersion: gateway.mulesoft.com/v1beta1 kind: Configuration metadata: name: circuit-breaker
namespace: test-ns spec: circuitBreaker: thresholds: maxConnections: 1 maxPendingRequests: 1
maxRequests: 1 maxRetries: 1 maxConnectionPools: 1

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum connections</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum pending requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p>Maximum requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum retries</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p>Maximum connection pools</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

> [!NOTE] For Managed Flex Gateways or Connected Mode, each API instance has its own independent
> limit when requesting the same upstream, allowing each to use the full maximum.

<!-- document id=5a2307bbb322d38d9d4a8eaa5ef008890ca6e3334c4f9ced46453b1178e29b6b url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.13
---

# Circuit Breaker Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Circuit Breaker</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Prevents an upstream from receiving too many requests or connections</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-circuit-breaker-release-notes">Circuit Breaker</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>503 - Service Unavailable</p></div></div></td></tr></tbody></table>

## Summary

The Circuit Breaker policy prevents upstream services from receiving too many requests or
connections at a time. If the defined maximums are reached, Omni Gateway returns a
`503 - Service Unavailable` error.

For Managed Omni Gateways or Connected Mode, each API instance has its own independent limit when
requesting the same upstream, allowing each to use the full maximum. In Local Mode, the limits are
shared among different API instances, so they must all adhere to the same upstream maximum. For all
modes, maximums are not distributed across replicas; each Gateway can use the full maximum.

The Circuit Breaker policy is an extension of the Envoy upstream clusters circuit breaking feature.
To learn more about the Envoy’s circuit breaking, see
[Circuit Breaking](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html)
in the Envoy documentation.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: upstream-policy spec:
targetRef: Kind: Service name: upstream policyRef: name: circuit-breaker-flex config: thresholds:
maxConnections: <number> // OPTIONAL maxPendingRequests: <number> // OPTIONAL maxRequests: <number>
// OPTIONAL maxRetries: <number> // OPTIONAL maxConnectionPools: <number> // OPTIONAL

> [!NOTE] For Local Mode, the limits are not independent, so different API instances share the
> maximums for an upstream.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumConnections</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumPendingRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRetries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p><code>maximumConnectionPools</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example defines a policy that supports a maximum of one request at a time:

apiVersion: gateway.mulesoft.com/v1beta1 kind: Configuration metadata: name: circuit-breaker
namespace: test-ns spec: circuitBreaker: thresholds: maxConnections: 1 maxPendingRequests: 1
maxRequests: 1 maxRetries: 1 maxConnectionPools: 1

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum connections</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum pending requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p>Maximum requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum retries</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p>Maximum connection pools</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

> [!NOTE] For Managed Omni Gateways or Connected Mode, each API instance has its own independent
> limit when requesting the same upstream, allowing each to use the full maximum.

<!-- document id=621f46a57e4d59e450f15e0a045666a2c00bd985b9821e4b9f385dd7fb2c19fe url=/mulesoft/current/en-us/gateway/1.9/policies-outbound-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.9
---

# Circuit Breaker Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Circuit Breaker</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Prevents an upstream from receiving too many requests or connections</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>503 - Service Unavailable</p></div></div></td></tr></tbody></table>

## Summary

The Circuit Breaker policy prevents upstream services from receiving too many requests or
connections at a time. If the defined maximums are reached, Flex Gateway returns a
`503 - Service Unavailable` error.

For Managed Flex Gateways or Connected Mode, each API instance has its own independent limit when
requesting the same upstream, allowing each to use the full maximum. In Local Mode, the limits are
shared among different API instances, so they must all adhere to the same upstream maximum. For all
modes, maximums are not distributed across replicas; each Gateway can use the full maximum.

The Circuit Breaker policy is an extension of the Envoy upstream clusters circuit breaking feature.
To learn more about the Envoy’s circuit breaking, see
[Circuit Breaking](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html)
in the Envoy documentation.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: upstream-policy spec:
targetRef: Kind: Service name: upstream policyRef: name: circuit-breaker-flex config: thresholds:
maxConnections: <number> // OPTIONAL maxPendingRequests: <number> // OPTIONAL maxRequests: <number>
// OPTIONAL maxRetries: <number> // OPTIONAL maxConnectionPools: <number> // OPTIONAL

> [!NOTE] For Local Mode, the limits are not independent, so different API instances share the
> maximums for an upstream.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumConnections</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumPendingRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRetries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p><code>maximumConnectionPools</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example defines a policy that supports a maximum of one request at a time:

apiVersion: gateway.mulesoft.com/v1beta1 kind: Configuration metadata: name: circuit-breaker
namespace: test-ns spec: circuitBreaker: thresholds: maxConnections: 1 maxPendingRequests: 1
maxRequests: 1 maxRetries: 1 maxConnectionPools: 1

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum connections</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum pending requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p>Maximum requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum retries</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p>Maximum connection pools</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

> [!NOTE] For Managed Flex Gateways or Connected Mode, each API instance has its own independent
> limit when requesting the same upstream, allowing each to use the full maximum.

<!-- document id=2100fd1f51782090e725bd6cbd6dd17fa892a03a86c454b9900fef5b4cb23f58 url=/mulesoft/current/en-us/gateway/latest/policies-outbound-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Circuit Breaker Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Circuit Breaker</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Prevents an upstream from receiving too many requests or connections</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-circuit-breaker-release-notes">Circuit Breaker</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>503 - Service Unavailable</p></div></div></td></tr></tbody></table>

## Summary

The Circuit Breaker policy prevents upstream services from receiving too many requests or
connections at a time. If the defined maximums are reached, Omni Gateway returns a
`503 - Service Unavailable` error.

This policy overrides the circuit breaker thresholds set in Runtime Manager or a Configuration
resource for the API instance you apply it to. To change the gateway-level thresholds, see
[Configure Circuit Breaker for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-circuit-breaker) or
[Configure Circuit Breaker in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-circuit-breaker).

For Managed Omni Gateways or Connected Mode, each API instance has its own independent limit when
requesting the same upstream, allowing each to use the full maximum. In Local Mode, the limits are
shared among different API instances, so they must all adhere to the same upstream maximum. For all
modes, maximums are not distributed across replicas; each Gateway can use the full maximum.

The Circuit Breaker policy is an extension of the Envoy upstream clusters circuit breaking feature.
To learn more about the Envoy’s circuit breaking, see
[Circuit Breaking](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html)
in the Envoy documentation.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: upstream-policy spec:
targetRef: Kind: Service name: upstream policyRef: name: circuit-breaker-flex config: thresholds:
maxConnections: <number> // OPTIONAL maxPendingRequests: <number> // OPTIONAL maxRequests: <number>
// OPTIONAL maxRetries: <number> // OPTIONAL maxConnectionPools: <number> // OPTIONAL

> [!NOTE] For Local Mode, the limits are not independent, so different API instances share the
> maximums for an upstream.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumConnections</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumPendingRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRetries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p><code>maximumConnectionPools</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example defines a policy that supports a maximum of one request at a time:

apiVersion: gateway.mulesoft.com/v1beta1 kind: Configuration metadata: name: circuit-breaker
namespace: test-ns spec: circuitBreaker: thresholds: maxConnections: 1 maxPendingRequests: 1
maxRequests: 1 maxRetries: 1 maxConnectionPools: 1

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum connections</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum pending requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p>Maximum requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum retries</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p>Maximum connection pools</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

> [!NOTE] For Managed Omni Gateways or Connected Mode, each API instance has its own independent
> limit when requesting the same upstream, allowing each to use the full maximum.

<!-- document id=ea48e0dae38905ab2f0bed0a33f9cb6bb574ec90a8b1cc145b31c344c762fb14 url=/mulesoft/current/en-us/gateway/1.12/policies-included-client-id-enforcement.md -->

---
product: Omni Gateway
version: 1.12
keywords: clientid enforcement, api gateway, flex gateway, gateway, policy
---

# Client ID Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Client ID Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Compliance</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP Fault error</p></td></tr></tbody></table>

## Summary

The Client ID Enforcement policy restricts access to a protected resource by allowing requests only
from registered client applications. The policy ensures that the client credentials sent on each
request have been approved to consume the API.

When a client application is registered in Anypoint Platform, a pair of credentials consisting of a
client ID and client secret is generated. When the client application requests access to an API, a
contract is created between the application and that API. An API that is protected with a Client ID
Enforcement policy is accessible only to applications that have an approved contract.

When you apply a Client ID Enforcement policy, access to your API is tracked by reporting the client
ID along with the analytics events.

Default policies that internally enforce client application credentials include:

- [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting-sla)

- [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-openid-token-enforcement)

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-jwt-validation)

Although token enforcement policies can optionally skip client validation, it is recommended that
you enforce the validation to ensure that the token is associated to an approved contract.

## Configuring Policy Parameters

### Flex Gateway Local Mode

Client ID Enforcement policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Credentials origin</p></div></div></td><td><div><div><p>Specifies from where in the request to extract the values:</p></div><div><ul><li><p>HTTP Basic Authentication Header: Requires credentials as part of the authorization header. The application consuming the API must use the basic authentication scheme to send the credentials in the requests.</p></li><li><p>Custom Expression: Accepts a DataWeave 2.0 expression each for client ID and client secret, indicating where to extract the credentials from the request. Use this option to send the credentials in a custom header or any other format. You can leave the field blank to configure the client secret requirement as optional.</p></li></ul></div></div></td><td><div><div><p>Must choose from one of the options.</p></div></div></td></tr><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client ID from API requests.</p></div></div></td><td><div><div><p>Yes.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client secret from API requests.</p></div></div></td><td><div><div><p>No.</p></div></div></td></tr></tbody></table>

## How This Policy Works

Before a client application is allowed to consume an API protected by a Client ID Enforcement
policy, the client application must request access to the API. After an approved contract exists
between the client application and the API, every request must include the client application
credentials in compliance with how the policy is configured.

For example, if the policy is configured to expect a client ID and client secret as query
parameters, the application must send those credentials in the request. To enforce this, add a
`client-id-required` RAML trait to the API specification:

traits: client-id-required: queryParameters: client\_id: type: string client\_secret: type: string

Apply the trait to the resources or methods using the `is` RAML attribute:

/example: get: is: \[client-id-required\] description: Example description

## Configuring How the Policy Obtains Credentials

You can configure the policy to extract either both the client ID and client secret, or only the
client ID from the HTTP request by using a variety of custom DataWeave 2.0 expressions. The
following examples use a client ID of '1234' and a client secret of 'abcd'.

### Obtaining Credentials Using HTTP Headers

Example request using curl:

```text
curl "http://localhost/myResource" -H "client_id:1234" -H "client_secret:abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.headers['client_id']]
#[attributes.headers['client_secret']]
```

In this example, the policy is configured to expect two headers: client\_id and client\_secret, with
the pair of credentials. The policy is flexible to allow other types of headers also. This is the
default configuration for the policy.

### Obtaining Credentials Using HTTP Query Parameters

Example request using curl:

```text
curl "http://localhost/myResource?client_id=1234&client_secret=abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.queryParams.'client_id']
#[attributes.queryParams.'client_secret']
```

In this example, the requester must send the two specified query parameters with the request.
Although this is a supported configuration, it poses possible security risks. The recommended method
is to use headers. A [subset](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support) of DataWeave 2.0 is supported.

### Obtaining Credentials Using HTTP Request Payload

Example request using curl:

```text
curl "http://localhost/myResource" -d '{"client_id":"1234", "client_secret":"abcd"}' -X POST
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[payload.client_id]
#[payload.client_secret]
```

Although you can configure the policy to obtain the credentials from the request payload, this
option is not recommended because it is harder to reflect in the API specification.

### Obtaining Credentials Using Basic Authorization header

Example request using curl:

```text
curl "http://localhost/myResource" -u 1234:abcd
```

## Configuring API Specifications

The Client ID Enforcement policy requires changes in your API specification to implement the
credentials requirement. You can find the RAML or OAS snippet link containing the RAML or OAS code
you need to add to the API specification in the corresponding policy. You can access this code from
the list of applied policies in the Policies tab of your API specification in API Manager.

## Policy Output

When an HTTP request is performed against a protected resource for which the Client ID Enforcement
policy is applied, and the client application credentials are invalid or unauthorized, the HTTP
response includes a WWW Authenticate header with the following values:

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Custom mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Client-ID-Enforcement'</p></td></tr><tr><td><p><strong>Basic Auth mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Basic realm="mule-realm"</p></td></tr></tbody></table>

For SOAP applications, the response is a SOAP error.

## See Also

- [Managing API Instance Contracts on API Manager](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task)

- [Getting Client ID and Client Secret of a Registered Client App](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task)

- [Reviewing SLA Tiers Concepts](https://docs.mulesoft.com/api-manager/latest/defining-sla-tiers)

<!-- document id=4e0077af3106371bdbd70b737ffcfde0cf87e4b030a1267d8fe9d2aa07a9fa78 url=/mulesoft/current/en-us/gateway/1.13/policies-included-client-id-enforcement.md -->

---
product: Omni Gateway
version: 1.13
keywords: clientid enforcement, api gateway, flex gateway, gateway, policy
---

# Client ID Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Client ID Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Compliance</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/client-id-enforcement-release-notes">Client ID Enforcement</a></p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP Fault error</p></td></tr></tbody></table>

## Summary

The Client ID Enforcement policy restricts access to a protected resource by allowing requests only
from registered client applications. The policy ensures that the client credentials sent on each
request have been approved to consume the API.

When a client application is registered in Anypoint Platform, a pair of credentials consisting of a
client ID and client secret is generated. When the client application requests access to an API, a
contract is created between the application and that API. An API that is protected with a Client ID
Enforcement policy is accessible only to applications that have an approved contract.

When you apply a Client ID Enforcement policy, access to your API is tracked by reporting the client
ID along with the analytics events.

Default policies that internally enforce client application credentials include:

- [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting-sla)

- [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-openid-token-enforcement)

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-jwt-validation)

Although token enforcement policies can optionally skip client validation, it is recommended that
you enforce the validation to ensure that the token is associated to an approved contract.

## Configuring Policy Parameters

### Omni Gateway Local Mode

Client ID Enforcement policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Credentials origin</p></div></div></td><td><div><div><p>Specifies from where in the request to extract the values:</p></div><div><ul><li><p>HTTP Basic Authentication Header: Requires credentials as part of the authorization header. The application consuming the API must use the basic authentication scheme to send the credentials in the requests.</p></li><li><p>Custom Expression: Accepts a DataWeave 2.0 expression each for client ID and client secret, indicating where to extract the credentials from the request. Use this option to send the credentials in a custom header or any other format. You can leave the field blank to configure the client secret requirement as optional.</p></li></ul></div></div></td><td><div><div><p>Must choose from one of the options.</p></div></div></td></tr><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client ID from API requests.</p></div></div></td><td><div><div><p>Yes.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client secret from API requests.</p></div></div></td><td><div><div><p>No.</p></div></div></td></tr></tbody></table>

## How This Policy Works

Before a client application is allowed to consume an API protected by a Client ID Enforcement
policy, the client application must request access to the API. After an approved contract exists
between the client application and the API, every request must include the client application
credentials in compliance with how the policy is configured.

For example, if the policy is configured to expect a client ID and client secret as query
parameters, the application must send those credentials in the request. To enforce this, add a
`client-id-required` RAML trait to the API specification:

traits: client-id-required: queryParameters: client\_id: type: string client\_secret: type: string

Apply the trait to the resources or methods using the `is` RAML attribute:

/example: get: is: \[client-id-required\] description: Example description

## Configuring How the Policy Obtains Credentials

You can configure the policy to extract either both the client ID and client secret, or only the
client ID from the HTTP request by using a variety of custom DataWeave 2.0 expressions. The
following examples use a client ID of '1234' and a client secret of 'abcd'.

### Obtaining Credentials Using HTTP Headers

Example request using curl:

```text
curl "http://localhost/myResource" -H "client_id:1234" -H "client_secret:abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.headers['client_id']]
#[attributes.headers['client_secret']]
```

In this example, the policy is configured to expect two headers: client\_id and client\_secret, with
the pair of credentials. The policy is flexible to allow other types of headers also. This is the
default configuration for the policy.

### Obtaining Credentials Using HTTP Query Parameters

Example request using curl:

```text
curl "http://localhost/myResource?client_id=1234&client_secret=abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.queryParams.'client_id']
#[attributes.queryParams.'client_secret']
```

In this example, the requester must send the two specified query parameters with the request.
Although this is a supported configuration, it poses possible security risks. The recommended method
is to use headers. A [subset](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support) of DataWeave 2.0 is supported.

### Obtaining Credentials Using HTTP Request Payload

Example request using curl:

```text
curl "http://localhost/myResource" -d '{"client_id":"1234", "client_secret":"abcd"}' -X POST
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[payload.client_id]
#[payload.client_secret]
```

Although you can configure the policy to obtain the credentials from the request payload, this
option is not recommended because it is harder to reflect in the API specification.

### Obtaining Credentials Using Basic Authorization header

Example request using curl:

```text
curl "http://localhost/myResource" -u 1234:abcd
```

## Configuring API Specifications

The Client ID Enforcement policy requires changes in your API specification to implement the
credentials requirement. You can find the RAML or OAS snippet link containing the RAML or OAS code
you need to add to the API specification in the corresponding policy. You can access this code from
the list of applied policies in the Policies tab of your API specification in API Manager.

## Policy Output

When an HTTP request is performed against a protected resource for which the Client ID Enforcement
policy is applied, and the client application credentials are invalid or unauthorized, the HTTP
response includes a WWW Authenticate header with the following values:

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Custom mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Client-ID-Enforcement'</p></td></tr><tr><td><p><strong>Basic Auth mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Basic realm="mule-realm"</p></td></tr></tbody></table>

For SOAP applications, the response is a SOAP error.

## See Also

- [Managing API Instance Contracts on API Manager](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task)

- [Getting Client ID and Client Secret of a Registered Client App](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task)

- [Reviewing SLA Tiers Concepts](https://docs.mulesoft.com/api-manager/latest/defining-sla-tiers)

<!-- document id=c699610bf59c873c749545234f085f9645fdd7102968d64e1e7d4abe55a4faf7 url=/mulesoft/current/en-us/gateway/1.9/policies-included-client-id-enforcement.md -->

---
product: Omni Gateway
version: 1.9
keywords: clientid enforcement, api gateway, flex gateway, gateway, policy
---

# Client ID Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Client ID Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Compliance</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP Fault error</p></td></tr></tbody></table>

## Summary

The Client ID Enforcement policy restricts access to a protected resource by allowing requests only
from registered client applications. The policy ensures that the client credentials sent on each
request have been approved to consume the API.

When a client application is registered in Anypoint Platform, a pair of credentials consisting of a
client ID and client secret is generated. When the client application requests access to an API, a
contract is created between the application and that API. An API that is protected with a Client ID
Enforcement policy is accessible only to applications that have an approved contract.

When you apply a Client ID Enforcement policy, access to your API is tracked by reporting the client
ID along with the analytics events.

Default policies that internally enforce client application credentials include:

- [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting-sla)

- [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-openid-token-enforcement)

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-jwt-validation)

Although token enforcement policies can optionally skip client validation, it is recommended that
you enforce the validation to ensure that the token is associated to an approved contract.

## Configuring Policy Parameters

### Flex Gateway Local Mode

Client ID Enforcement policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Credentials origin</p></div></div></td><td><div><div><p>Specifies from where in the request to extract the values:</p></div><div><ul><li><p>HTTP Basic Authentication Header: Requires credentials as part of the authorization header. The application consuming the API must use the basic authentication scheme to send the credentials in the requests.</p></li><li><p>Custom Expression: Accepts a DataWeave 2.0 expression each for client ID and client secret, indicating where to extract the credentials from the request. Use this option to send the credentials in a custom header or any other format. You can leave the field blank to configure the client secret requirement as optional.</p></li></ul></div></div></td><td><div><div><p>Must choose from one of the options.</p></div></div></td></tr><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client ID from API requests.</p></div></div></td><td><div><div><p>Yes.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client secret from API requests.</p></div></div></td><td><div><div><p>No.</p></div></div></td></tr></tbody></table>

## How This Policy Works

Before a client application is allowed to consume an API protected by a Client ID Enforcement
policy, the client application must request access to the API. After an approved contract exists
between the client application and the API, every request must include the client application
credentials in compliance with how the policy is configured.

For example, if the policy is configured to expect a client ID and client secret as query
parameters, the application must send those credentials in the request. To enforce this, add a
`client-id-required` RAML trait to the API specification:

traits: client-id-required: queryParameters: client\_id: type: string client\_secret: type: string

Apply the trait to the resources or methods using the `is` RAML attribute:

/example: get: is: \[client-id-required\] description: Example description

## Configuring How the Policy Obtains Credentials

You can configure the policy to extract either both the client ID and client secret, or only the
client ID from the HTTP request by using a variety of custom DataWeave 2.0 expressions. The
following examples use a client ID of '1234' and a client secret of 'abcd'.

### Obtaining Credentials Using HTTP Headers

Example request using curl:

```text
curl "http://localhost/myResource" -H "client_id:1234" -H "client_secret:abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.headers['client_id']]
#[attributes.headers['client_secret']]
```

In this example, the policy is configured to expect two headers: client\_id and client\_secret, with
the pair of credentials. The policy is flexible to allow other types of headers also. This is the
default configuration for the policy.

### Obtaining Credentials Using HTTP Query Parameters

Example request using curl:

```text
curl "http://localhost/myResource?client_id=1234&client_secret=abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.queryParams.'client_id']
#[attributes.queryParams.'client_secret']
```

In this example, the requester must send the two specified query parameters with the request.
Although this is a supported configuration, it poses possible security risks. The recommended method
is to use headers. A [subset](https://docs.mulesoft.com/gateway/1.9/policies-flex-dataweave-support) of DataWeave 2.0 is supported.

### Obtaining Credentials Using HTTP Request Payload

Example request using curl:

```text
curl "http://localhost/myResource" -d '{"client_id":"1234", "client_secret":"abcd"}' -X POST
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[payload.client_id]
#[payload.client_secret]
```

Although you can configure the policy to obtain the credentials from the request payload, this
option is not recommended because it is harder to reflect in the API specification.

### Obtaining Credentials Using Basic Authorization header

Example request using curl:

```text
curl "http://localhost/myResource" -u 1234:abcd
```

## Configuring API Specifications

The Client ID Enforcement policy requires changes in your API specification to implement the
credentials requirement. You can find the RAML or OAS snippet link containing the RAML or OAS code
you need to add to the API specification in the corresponding policy. You can access this code from
the list of applied policies in the Policies tab of your API specification in API Manager.

## Policy Output

When an HTTP request is performed against a protected resource for which the Client ID Enforcement
policy is applied, and the client application credentials are invalid or unauthorized, the HTTP
response includes a WWW Authenticate header with the following values:

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Custom mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Client-ID-Enforcement'</p></td></tr><tr><td><p><strong>Basic Auth mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Basic realm="mule-realm"</p></td></tr></tbody></table>

For SOAP applications, the response is a SOAP error.

## See Also

- [Managing API Instance Contracts on API Manager](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task)

- [Getting Client ID and Client Secret of a Registered Client App](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task)

- [Reviewing SLA Tiers Concepts](https://docs.mulesoft.com/api-manager/latest/defining-sla-tiers)

<!-- document id=04ff5d78a32f7ef2c45ee6d58afa461ebac32c0334695690ce21925775af6f61 url=/mulesoft/current/en-us/gateway/latest/policies-included-client-id-enforcement.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: clientid enforcement, api gateway, flex gateway, gateway, policy
---

# Client ID Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Client ID Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Compliance</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/client-id-enforcement-release-notes">Client ID Enforcement</a></p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP Fault error</p></td></tr></tbody></table>

## Summary

The Client ID Enforcement policy restricts access to a protected resource by allowing requests only
from registered client applications. The policy ensures that the client credentials sent on each
request have been approved to consume the API.

When a client application is registered in Anypoint Platform, a pair of credentials consisting of a
client ID and client secret is generated. When the client application requests access to an API, a
contract is created between the application and that API. An API that is protected with a Client ID
Enforcement policy is accessible only to applications that have an approved contract.

When you apply a Client ID Enforcement policy, access to your API is tracked by reporting the client
ID along with the analytics events.

Default policies that internally enforce client application credentials include:

- [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting-sla)

- [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-openid-token-enforcement)

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation)

Although token enforcement policies can optionally skip client validation, it is recommended that
you enforce the validation to ensure that the token is associated to an approved contract.

## Configuring Policy Parameters

### Omni Gateway Local Mode

Client ID Enforcement policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Credentials origin</p></div></div></td><td><div><div><p>Specifies from where in the request to extract the values:</p></div><div><ul><li><p>HTTP Basic Authentication Header: Requires credentials as part of the authorization header. The application consuming the API must use the basic authentication scheme to send the credentials in the requests.</p></li><li><p>Custom Expression: Accepts a DataWeave 2.0 expression each for client ID and client secret, indicating where to extract the credentials from the request. Use this option to send the credentials in a custom header or any other format. You can leave the field blank to configure the client secret requirement as optional.</p></li></ul></div></div></td><td><div><div><p>Must choose from one of the options.</p></div></div></td></tr><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client ID from API requests.</p></div></div></td><td><div><div><p>Yes.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to use for obtaining the client secret from API requests.</p></div></div></td><td><div><div><p>No.</p></div></div></td></tr></tbody></table>

## How This Policy Works

Before a client application is allowed to consume an API protected by a Client ID Enforcement
policy, the client application must request access to the API. After an approved contract exists
between the client application and the API, every request must include the client application
credentials in compliance with how the policy is configured.

For example, if the policy is configured to expect a client ID and client secret as query
parameters, the application must send those credentials in the request. To enforce this, add a
`client-id-required` RAML trait to the API specification:

traits: client-id-required: queryParameters: client\_id: type: string client\_secret: type: string

Apply the trait to the resources or methods using the `is` RAML attribute:

/example: get: is: \[client-id-required\] description: Example description

## Configuring How the Policy Obtains Credentials

You can configure the policy to extract either both the client ID and client secret, or only the
client ID from the HTTP request by using a variety of custom DataWeave 2.0 expressions. The
following examples use a client ID of '1234' and a client secret of 'abcd'.

### Obtaining Credentials Using HTTP Headers

Example request using curl:

```text
curl "http://localhost/myResource" -H "client_id:1234" -H "client_secret:abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.headers['client_id']]
#[attributes.headers['client_secret']]
```

In this example, the policy is configured to expect two headers: client\_id and client\_secret, with
the pair of credentials. The policy is flexible to allow other types of headers also. This is the
default configuration for the policy.

### Obtaining Credentials Using HTTP Query Parameters

Example request using curl:

```text
curl "http://localhost/myResource?client_id=1234&client_secret=abcd"
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[attributes.queryParams.'client_id']
#[attributes.queryParams.'client_secret']
```

In this example, the requester must send the two specified query parameters with the request.
Although this is a supported configuration, it poses possible security risks. The recommended method
is to use headers. A [subset](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support) of DataWeave 2.0 is supported.

### Obtaining Credentials Using HTTP Request Payload

Example request using curl:

```text
curl "http://localhost/myResource" -d '{"client_id":"1234", "client_secret":"abcd"}' -X POST
```

Example DataWeave 2.0 expression to be used when configuring the policy:

```text
#[payload.client_id]
#[payload.client_secret]
```

Although you can configure the policy to obtain the credentials from the request payload, this
option is not recommended because it is harder to reflect in the API specification.

### Obtaining Credentials Using Basic Authorization header

Example request using curl:

```text
curl "http://localhost/myResource" -u 1234:abcd
```

## Configuring API Specifications

The Client ID Enforcement policy requires changes in your API specification to implement the
credentials requirement. You can find the RAML or OAS snippet link containing the RAML or OAS code
you need to add to the API specification in the corresponding policy. You can access this code from
the list of applied policies in the Policies tab of your API specification in API Manager.

## Policy Output

When an HTTP request is performed against a protected resource for which the Client ID Enforcement
policy is applied, and the client application credentials are invalid or unauthorized, the HTTP
response includes a WWW Authenticate header with the following values:

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Custom mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Client-ID-Enforcement'</p></td></tr><tr><td><p><strong>Basic Auth mode</strong></p></td><td><p>Header 'WWW-Authenticate'='Basic realm="mule-realm"</p></td></tr></tbody></table>

For SOAP applications, the response is a SOAP error.

## See Also

- [Managing API Instance Contracts on API Manager](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task)

- [Getting Client ID and Client Secret of a Registered Client App](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task)

- [Reviewing SLA Tiers Concepts](https://docs.mulesoft.com/api-manager/latest/defining-sla-tiers)

<!-- document id=789e825521756f904c0634a69f0c6fc9c4b796fb51058b2e3e6e4b5e79a3e372 url=/mulesoft/current/en-us/gateway/1.13/managed-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Circuit Breaker for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these circuit breaker thresholds:

- **Maximum Connections**  
  The maximum number of connections per API to an upstream service.

- **Maximum Pending Requests**  
  The maximum number of queued requests that can wait for a connection.

- **Maximum Requests**  
  The maximum number of outstanding requests to an upstream service.

- **Maximum Retries**  
  The maximum number of outstanding retries.

- **Maximum Connection Pools**  
  The maximum number of connection pools concurrently initiated to an upstream service.

> [!NOTE] When requests or connections exceed a threshold, Omni Gateway returns a
> `503 - Service Unavailable` error.

All thresholds are optional. For Managed Omni Gateways and Connected Mode, each API instance has its
own independent limit per upstream, so each can use the full threshold value. In Local Mode,
different API instances share limits for the same upstream. For all modes, each gateway replica can
use the full threshold value and limits aren’t distributed across replicas.

Configure circuit breaker thresholds for Managed Omni Gateway via:

- Runtime Manager runtime configurations: Applies to all API instances in the gateway after the
  gateway is deployed.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Circuit Breaker in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Circuit Breaker**.

6.  Set values for **Maximum Connections**, **Maximum Pending Requests**, **Maximum Requests**,
    **Maximum Retries**, and **Maximum Connection Pools**.

7.  Apply the changes.

## Configure Circuit Breaker via Policies

Apply the Circuit Breaker policy to your API instance or upstream service:

- [Circuit Breaker Policy](https://docs.mulesoft.com/gateway/1.13/policies-outbound-circuit-breaker)

<!-- document id=52e70ab8505d960a089f5e12f7d3a6c670581d557b5ba643a5cb6b0386a9d90a url=/mulesoft/current/en-us/gateway/latest/managed-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Circuit Breaker for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Circuit breaker protection stops Omni Gateway from overwhelming an upstream service. When the number
of connections, requests, or retries to an upstream exceeds a configured threshold, the circuit
breaker rejects requests with a `503 - Service Unavailable` error until traffic returns to within
the threshold.

Omni Gateway offers these circuit breaker thresholds:

- **Maximum Connections**  
  The maximum number of connections per API to an upstream service.

- **Maximum Pending Requests**  
  The maximum number of queued requests that can wait for a connection.

- **Maximum Requests**  
  The maximum number of outstanding requests to an upstream service.

- **Maximum Retries**  
  The maximum number of outstanding retries.

- **Maximum Connection Pools**  
  The maximum number of connection pools concurrently initiated to an upstream service.

> [!NOTE] When requests or connections exceed a threshold, Omni Gateway returns a
> `503 - Service Unavailable` error.

All thresholds are optional. For Managed Omni Gateways and Connected Mode, each API instance has its
own independent limit per upstream, so each can use the full threshold value. In Local Mode,
different API instances share limits for the same upstream. For all modes, each gateway replica can
use the full threshold value and limits aren’t distributed across replicas.

Configure circuit breaker thresholds for Managed Omni Gateway via:

- Runtime Manager runtime configurations: Applies to all API instances in the gateway after the
  gateway is deployed.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set,
in this order of precedence:

1.  **Policy**: A policy applied to the API instance.

2.  **Runtime Manager runtime configuration**: Used if no policy value is set.

3.  **Built-in default**: Used if neither of the other values is set. A policy value overrides the
    gateway-level value for the API instance it’s applied to. API instances without the policy use
    the gateway-level value.

## Configure Circuit Breaker in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Circuit Breaker**.

6.  Set values for **Maximum Connections**, **Maximum Pending Requests**, **Maximum Requests**,
    **Maximum Retries**, and **Maximum Connection Pools**.

7.  Apply the changes.

## Configure Circuit Breaker via Policies

Apply the Circuit Breaker policy to your API instance or upstream service:

- [Circuit Breaker Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-circuit-breaker)

<!-- document id=0619c719f5fb7c2d9186039861055e2e9b048ed6d8943bcf632bf11a2f6bb61d url=/mulesoft/current/en-us/gateway/1.13/conn-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Circuit Breaker in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these circuit breaker thresholds:

- **Maximum Connections**  
  The maximum number of connections per API to an upstream service.

- **Maximum Pending Requests**  
  The maximum number of queued requests that can wait for a connection.

- **Maximum Requests**  
  The maximum number of outstanding requests to an upstream service.

- **Maximum Retries**  
  The maximum number of outstanding retries.

- **Maximum Connection Pools**  
  The maximum number of connection pools concurrently initiated to an upstream service.

> [!NOTE] When requests or connections exceed a threshold, Omni Gateway returns a
> `503 - Service Unavailable` error.

All thresholds are optional. For Managed Omni Gateways and Connected Mode, each API instance has its
own independent limit per upstream, so each can use the full threshold value. In Local Mode,
different API instances share limits for the same upstream. For all modes, each gateway replica can
use the full threshold value and limits aren’t distributed across replicas.

Configure circuit breaker thresholds in Connected Mode via:

- Runtime Manager runtime configurations: Applies to all API instances in the gateway.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Circuit Breaker in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Circuit Breaker**.

6.  Set values for **Maximum Connections**, **Maximum Pending Requests**, **Maximum Requests**,
    **Maximum Retries**, and **Maximum Connection Pools**.

7.  Apply the changes.

## Configure Circuit Breaker via YAML Configuration Resources

To update your circuit breaker thresholds, edit and then apply this configuration resource:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: circuit-breaker
spec:
  circuitBreaker:
    thresholds:
      maxConnections: <number>
      maxPendingRequests: <number>
      maxRequests: <number>
      maxRetries: <number>
      maxConnectionPools: <number>
```

## Configure Circuit Breaker via Policies

Apply the Circuit Breaker policy to your API instance or upstream service:

- [Circuit Breaker Policy](https://docs.mulesoft.com/gateway/1.13/policies-outbound-circuit-breaker)

<!-- document id=63b561e8a0cf0ab9e53809858f5a5e6fda00429494d4c9121e7a93a9831f40df url=/mulesoft/current/en-us/gateway/latest/conn-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Circuit Breaker in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Circuit breaker protection stops Omni Gateway from overwhelming an upstream service. When the number
of connections, requests, or retries to an upstream exceeds a configured threshold, the circuit
breaker rejects requests with a `503 - Service Unavailable` error until traffic returns to within
the threshold.

Omni Gateway offers these circuit breaker thresholds:

- **Maximum Connections**  
  The maximum number of connections per API to an upstream service.

- **Maximum Pending Requests**  
  The maximum number of queued requests that can wait for a connection.

- **Maximum Requests**  
  The maximum number of outstanding requests to an upstream service.

- **Maximum Retries**  
  The maximum number of outstanding retries.

- **Maximum Connection Pools**  
  The maximum number of connection pools concurrently initiated to an upstream service.

> [!NOTE] When requests or connections exceed a threshold, Omni Gateway returns a
> `503 - Service Unavailable` error.

All thresholds are optional. For Managed Omni Gateways and Connected Mode, each API instance has its
own independent limit per upstream, so each can use the full threshold value. In Local Mode,
different API instances share limits for the same upstream. For all modes, each gateway replica can
use the full threshold value and limits aren’t distributed across replicas.

Configure circuit breaker thresholds in Connected Mode via:

- Runtime Manager runtime configurations: Applies to all API instances in the gateway.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set,
in this order of precedence:

1.  **Policy**: A policy applied to the API instance.

2.  **Runtime Manager runtime configuration or Configuration resource**: Used if no policy value is
    set.

3.  **Built-in default**: Used if none of the other values is set. A policy value overrides the
    gateway-level value for the API instance it’s applied to. API instances without the policy use
    the gateway-level value.

## Configure Circuit Breaker in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Circuit Breaker**.

6.  Set values for **Maximum Connections**, **Maximum Pending Requests**, **Maximum Requests**,
    **Maximum Retries**, and **Maximum Connection Pools**.

7.  Apply the changes.

## Configure Circuit Breaker via YAML Configuration Resources

To update your circuit breaker thresholds, edit and then apply this configuration resource:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: circuit-breaker
spec:
  circuitBreaker:
    thresholds:
      maxConnections: <number>
      maxPendingRequests: <number>
      maxRequests: <number>
      maxRetries: <number>
      maxConnectionPools: <number>
```

## Configure Circuit Breaker via Policies

Apply the Circuit Breaker policy to your API instance or upstream service:

- [Circuit Breaker Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-circuit-breaker)

<!-- document id=257b294699ad8b4ee3c5a48391d43b89169537e9992be4a2c6e17806894a0fbb url=/mulesoft/current/en-us/gateway/1.13/local-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Circuit Breaker in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these circuit breaker thresholds:

- **Maximum Connections**  
  The maximum number of connections per API to an upstream service.

- **Maximum Pending Requests**  
  The maximum number of queued requests that can wait for a connection.

- **Maximum Requests**  
  The maximum number of outstanding requests to an upstream service.

- **Maximum Retries**  
  The maximum number of outstanding retries.

- **Maximum Connection Pools**  
  The maximum number of connection pools concurrently initiated to an upstream service.

> [!NOTE] When requests or connections exceed a threshold, Omni Gateway returns a
> `503 - Service Unavailable` error.

All thresholds are optional. For Managed Omni Gateways and Connected Mode, each API instance has its
own independent limit per upstream, so each can use the full threshold value. In Local Mode,
different API instances share limits for the same upstream. For all modes, each gateway replica can
use the full threshold value and limits aren’t distributed across replicas.

Configure circuit breaker thresholds in Local Mode via:

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Circuit Breaker via YAML Configuration Resources

To update your circuit breaker thresholds, edit and then apply this configuration resource:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: circuit-breaker
spec:
  circuitBreaker:
    thresholds:
      maxConnections: <number>
      maxPendingRequests: <number>
      maxRequests: <number>
      maxRetries: <number>
      maxConnectionPools: <number>
```

## Configure Circuit Breaker via Policies

Apply the Circuit Breaker policy to your API instance or upstream service:

- [Circuit Breaker Policy](https://docs.mulesoft.com/gateway/1.13/policies-outbound-circuit-breaker)

<!-- document id=3bf66bc37db399b2bc8043fc19d03269cadc08c2c2d6b4957ed706afc11a7bb2 url=/mulesoft/current/en-us/gateway/latest/local-circuit-breaker.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Circuit Breaker in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Circuit breaker protection stops Omni Gateway from overwhelming an upstream service. When the number
of connections, requests, or retries to an upstream exceeds a configured threshold, the circuit
breaker rejects requests with a `503 - Service Unavailable` error until traffic returns to within
the threshold.

Omni Gateway offers these circuit breaker thresholds:

- **Maximum Connections**  
  The maximum number of connections per API to an upstream service.

- **Maximum Pending Requests**  
  The maximum number of queued requests that can wait for a connection.

- **Maximum Requests**  
  The maximum number of outstanding requests to an upstream service.

- **Maximum Retries**  
  The maximum number of outstanding retries.

- **Maximum Connection Pools**  
  The maximum number of connection pools concurrently initiated to an upstream service.

> [!NOTE] When requests or connections exceed a threshold, Omni Gateway returns a
> `503 - Service Unavailable` error.

All thresholds are optional. For Managed Omni Gateways and Connected Mode, each API instance has its
own independent limit per upstream, so each can use the full threshold value. In Local Mode,
different API instances share limits for the same upstream. For all modes, each gateway replica can
use the full threshold value and limits aren’t distributed across replicas.

Configure circuit breaker thresholds in Local Mode via:

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Circuit Breaker via YAML Configuration Resources

To update your circuit breaker thresholds, edit and then apply this configuration resource:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: circuit-breaker
spec:
  circuitBreaker:
    thresholds:
      maxConnections: <number>
      maxPendingRequests: <number>
      maxRequests: <number>
      maxRetries: <number>
      maxConnectionPools: <number>
```

## Configure Circuit Breaker via Policies

Apply the Circuit Breaker policy to your API instance or upstream service:

- [Circuit Breaker Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-circuit-breaker)

<!-- document id=fff34feeb9c9688c7e7d81b1324f4400c3f11aab74db679f884afeae6d8b8d3c url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-k8-ingress-class.md -->

---
product: Omni Gateway
version: 1.12
---

# Configure Flex Gateway as an Ingress Controller in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Kubernetes deployments in Local Mode, Flex Gateway typically acts as an ingress controller that
manages external access to your Kubernetes cluster.

By default, Flex Gateways deployed on Kubernetes in Local Mode are configured as ingress controllers
and can consume `Ingress` resources. The ingress controller configuration is defined in the
`IngressClass` resource parameters in the Flex Gateway Helm chart.

In Kubernetes terminology, `IngressClass` resources configure a gateway as an ingress controller,
and `Ingress` resources configure a routing between the ingress controller and the Kubernetes
services it controls. For a detailed explanation of Kubernetes `IngressClass` resources and
`Ingress` resources, see
[Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

In the Helm chart, you can edit the `IngressClass` configuration or disable the ingress controller
functionality.

## Before You Begin

1.  [Download Flex Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-install#kubernetes).

2.  [Register and Run Flex Gateway in a Kubernetes Cluster in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

## Ingress Class Parameters

The Helm chart includes the following default `IngressClass` parameters and values:

```helm
ingressClass.enabled: true
ingressClass.name: "{releaseName}-{namespace}"
ingressClass.setAsDefault: false
```

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td><td><p>Possible values</p></td></tr><tr><td><p><code>ingressClass.enabled</code></p></td><td><p>Enables Flex Gateway as an <code>IngressClass</code> resource</p></td><td><p><code>true</code> or <code>false</code></p></td></tr><tr><td><p><code>ingressClass.name</code></p></td><td><p>The name of the <code>IngressClass</code></p></td><td><p>Any string</p></td></tr><tr><td><p><code>ingressClass.setAsDefault</code></p></td><td><p>Sets Flex Gateway as the default <code>IngressClass</code></p></td><td><p><code>true</code> or <code>false</code></p></td></tr></tbody></table>

Setting `ingressClass.setAsDefault: true` defines the Flex Gateway instance as the default
`IngressClass` resource for the cluster. The default `IngressClass` is the default ingress
controller for all `Ingress` resources you create in the cluster.

If there is no default `IngressClass`, or if the default `IngressClass` resource shouldn’t be the
ingress controller for a specific resource, you must manually define the ingress controller in the
`Ingress` resource.

You can modify the default `IngressClass` parameters during or after the initial installation of the
Helm chart. For more information about how to modify a Helm chart, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings)

## Creating Ingress Resources

After you [install a Helm chart into a namespace](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run-up#kubernetes), you can verify
your new `IngressClass` resource by running the following command:

```helm
kubectl get ingressclasses
```

To create an ingress routing:

1.  [Publish an API in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-publish-simple-api#kubernetes).

2.  Define the new API as a Kubernetes Service.  
    For more information about Kubernetes Service definitions, see
    [Defining a Service](https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service).

3.  Using `kubectl apply`, create an `Ingress` resource to define routing rules between the
    `IngressClass` Flex Gateway and the new Kubernetes Service:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: <metadata-name>
      annotations:
        flex-gateway.ingress.kubernetes.io/api-instance: <api-instance-name>.<namespace>
    spec:
      ingressClassName: <ingress-class-name>
      rules:
      - http: ...
    EOF
    ```

    The `annotations` field value must match the API instance name and namespace specified when the
    API was defined.

    Omit the `ingressClassName` field if the gateway instance is configured as the default ingress
    controller.

    For more information about `Ingress` resources, see
    [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

## See Also

- [Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management)

<!-- document id=1f18786c45ab37f3ee35a836658e960b29fea47cc9ea048b010e49ef64c8e965 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-k8-ingress-class.md -->

---
product: Omni Gateway
version: 1.9
---

# Configure Flex Gateway as an Ingress Controller in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Kubernetes deployments in Local Mode, Flex Gateway typically acts as an ingress controller that
manages external access to your Kubernetes cluster.

By default, Flex Gateways deployed on Kubernetes in Local Mode are configured as ingress controllers
and can consume `Ingress` resources. The ingress controller configuration is defined in the
`IngressClass` resource parameters in the Flex Gateway Helm chart.

In Kubernetes terminology, `IngressClass` resources configure a gateway as an ingress controller,
and `Ingress` resources configure a routing between the ingress controller and the Kubernetes
services it controls. For a detailed explanation of Kubernetes `IngressClass` resources and
`Ingress` resources, see
[Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

In the Helm chart, you can edit the `IngressClass` configuration or disable the ingress controller
functionality.

## Before You Begin

1.  [Download Flex Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-install#kubernetes).

2.  [Register and Run Flex Gateway in a Kubernetes Cluster in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

## Ingress Class Parameters

The Helm chart includes the following default `IngressClass` parameters and values:

```helm
ingressClass.enabled: true
ingressClass.name: "{releaseName}-{namespace}"
ingressClass.setAsDefault: false
```

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td><td><p>Possible values</p></td></tr><tr><td><p><code>ingressClass.enabled</code></p></td><td><p>Enables Flex Gateway as an <code>IngressClass</code> resource</p></td><td><p><code>true</code> or <code>false</code></p></td></tr><tr><td><p><code>ingressClass.name</code></p></td><td><p>The name of the <code>IngressClass</code></p></td><td><p>Any string</p></td></tr><tr><td><p><code>ingressClass.setAsDefault</code></p></td><td><p>Sets Flex Gateway as the default <code>IngressClass</code></p></td><td><p><code>true</code> or <code>false</code></p></td></tr></tbody></table>

Setting `ingressClass.setAsDefault: true` defines the Flex Gateway instance as the default
`IngressClass` resource for the cluster. The default `IngressClass` is the default ingress
controller for all `Ingress` resources you create in the cluster.

If there is no default `IngressClass`, or if the default `IngressClass` resource shouldn’t be the
ingress controller for a specific resource, you must manually define the ingress controller in the
`Ingress` resource.

You can modify the default `IngressClass` parameters during or after the initial installation of the
Helm chart. For more information about how to modify a Helm chart, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings)

## Creating Ingress Resources

After you [install a Helm chart into a namespace](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run-up#kubernetes), you can verify
your new `IngressClass` resource by running the following command:

```helm
kubectl get ingressclasses
```

To create an ingress routing:

1.  [Publish an API in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-publish-simple-api#kubernetes).

2.  Define the new API as a Kubernetes Service.  
    For more information about Kubernetes Service definitions, see
    [Defining a Service](https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service).

3.  Using `kubectl apply`, create an `Ingress` resource to define routing rules between the
    `IngressClass` Flex Gateway and the new Kubernetes Service:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: <metadata-name>
      annotations:
        flex-gateway.ingress.kubernetes.io/api-instance: <api-instance-name>.<namespace>
    spec:
      ingressClassName: <ingress-class-name>
      rules:
      - http: ...
    EOF
    ```

    The `annotations` field value must match the API instance name and namespace specified when the
    API was defined.

    Omit the `ingressClassName` field if the gateway instance is configured as the default ingress
    controller.

    For more information about `Ingress` resources, see
    [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

## See Also

- [Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management)

<!-- document id=50e6be44a874e19f034053031ec989cdbac9d0a72277947970b64b62ef01fc14 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-env-variables.md -->

---
product: Omni Gateway
version: 1.12
---

# Configure Flex Gateway Environment Variables in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway provides these environment variables to configure your gateway:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p>FLEX_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a connection can be idle before it times out. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_STREAM_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>300</code></p></td><td><p>Maximum number of seconds a stream can remain idle without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex Gateway to upstream service) direction. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a stream between Flex Gateway and the upstream service can remain idle between requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_RESPONSE_TIMEOUT_SECONDS</p></td><td><p><code>15</code></p></td><td><p>Maximum number of seconds a Flex Gateway waits for a response from an upstream service. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_ENVOY_HEADERS_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Allows (<code>true</code>) or removes (<code>false</code>) Envoy headers from requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites">Requirements and Limits for Flex Gateway</a>.</p></td></tr><tr><td><p>FLEX_REWRITE_HOST_HEADER</p></td><td><p><code>true</code></p></td><td><p>Rewrite HTTP Host header to match upstream.</p></td></tr><tr><td><p>FLEX_REMOVE_SERVER_HEADER</p></td><td><p><code>false</code></p></td><td><p>Removes the <code>Server</code> HTTP response header from outbound responses when set to <code>true</code>. Set to <code>true</code> to reduce exposure of server implementation details for security or compliance purposes.</p></td></tr><tr><td><p>FLEX_HEADER_RAW_VALUE_ENABLE</p></td><td><p>`tru`e</p></td><td><p>Controls header encoding for external authorization. Set to <code>false</code> to send headers encoded in UTF-8. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/policies-included-external-authorization">External Authorization Policy</a>.</p></td></tr><tr><td><p>FLEX_FORWARD_CLIENT_CERT_DETAILS</p></td><td><p><code>SANITIZE</code></p></td><td><p>Controls how the <code>x-forwarded-client-cert</code> (XFCC) HTTP header is handled. Supported values are <code>SANITIZE</code>, <code>FORWARD_ONLY</code>, <code>APPEND_FORWARD</code>, <code>SANITIZE_SET</code>, and <code>ALWAYS_FORWARD_ONLY</code>. For more information, see <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails">HTTP connection manager (proto)</a> in the Envoy documentation.</p></td></tr><tr><td><p>FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES</p></td><td><p><code>1048576</code> (1 MB)</p></td><td><p>Maximum size, in bytes, of read and write buffers for new connections. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites">Requirements and Limits for Flex Gateway</a>.</p></td></tr><tr><td><p>FLEX_DATASOURCE_CONTROL_NODE_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Enable configuration caching in Redis shared storage for Connected Mode replicas. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-conn-replica-caching">Configuring Flex Gateway Configuration Caching in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SERVICE_ENVOY_DRAIN_TIME</p></td><td><p><code>25</code></p></td><td><p>Drain period in seconds during shutdown before Flex Gateway exits gracefully. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-conn-monitor">Monitoring in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SYNC_DEBOUNCE_TIME</p></td><td><p>"5s"</p></td><td><p>Specifies the amount of time to wait after detecting a configuration change before applying it. This prevents excessive reloading during rapid successive changes. The value must be a valid duration string, such as <code>"5s"</code> or <code>"500ms"</code>.</p></td></tr><tr><td><p>FLEX_LOG_LEVEL</p></td><td><p><code>4</code> (INFO)</p></td><td><p>Sets the logging level for Flex Gateway. For the environment variable configuration of log level, you specify a number that corresponds to the log level. Supported values are NONE:`-1`, FATAL:`0`, ERROR:`1`, WARN:`2`, INFO:`4`, DEBUG:`8`, and TRACE:`16`.</p></td></tr><tr><td><p>FLEX_CONFIG</p></td><td><p>N/A</p></td><td><p>Provides Flex Gateway registration and configuration as a YAML-formatted string. The YAML content must be properly escaped to preserve special characters. Provide your registration and configuration as a string if deploying environments where file mounting isn’t practical, such as Amazon ECS or Azure Container Apps.</p></td></tr></tbody></table>

<!-- document id=b2f43c0dd7952d0a96154b521175005432d15a86d98626e6e89ce17f104341fc url=/mulesoft/current/en-us/gateway/1.12/flex-local-env-variables.md -->

---
product: Omni Gateway
version: 1.12
---

# Configure Flex Gateway Environment Variables in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway provides these environment variables to configure your gateway:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p>FLEX_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a connection can be idle before it times out. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_STREAM_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>300</code></p></td><td><p>Maximum number of seconds a stream can remain idle without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex Gateway to upstream service) direction. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a stream between Flex Gateway and the upstream service can remain idle between requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_RESPONSE_TIMEOUT_SECONDS</p></td><td><p><code>15</code></p></td><td><p>Maximum number of seconds a Flex Gateway waits for a response from an upstream service. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_ENVOY_HEADERS_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Allows (<code>true</code>) or removes (<code>false</code>) Envoy headers from requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites">Requirements and Limits for Flex Gateway</a>.</p></td></tr><tr><td><p>FLEX_REWRITE_HOST_HEADER</p></td><td><p><code>true</code></p></td><td><p>Rewrite HTTP Host header to match upstream.</p></td></tr><tr><td><p>FLEX_REMOVE_SERVER_HEADER</p></td><td><p><code>false</code></p></td><td><p>Removes the <code>Server</code> HTTP response header from outbound responses when set to <code>true</code>. Set to <code>true</code> to reduce exposure of server implementation details for security or compliance purposes.</p></td></tr><tr><td><p>FLEX_HEADER_RAW_VALUE_ENABLE</p></td><td><p>`tru`e</p></td><td><p>Controls header encoding for external authorization. Set to <code>false</code> to send headers encoded in UTF-8. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/policies-included-external-authorization">External Authorization Policy</a>.</p></td></tr><tr><td><p>FLEX_FORWARD_CLIENT_CERT_DETAILS</p></td><td><p><code>SANITIZE</code></p></td><td><p>Controls how the <code>x-forwarded-client-cert</code> (XFCC) HTTP header is handled. Supported values are <code>SANITIZE</code>, <code>FORWARD_ONLY</code>, <code>APPEND_FORWARD</code>, <code>SANITIZE_SET</code>, and <code>ALWAYS_FORWARD_ONLY</code>. For more information, see <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails">HTTP connection manager (proto)</a> in the Envoy documentation.</p></td></tr><tr><td><p>FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES</p></td><td><p><code>1048576</code> (1 MB)</p></td><td><p>Maximum size, in bytes, of read and write buffers for new connections. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites">Requirements and Limits for Flex Gateway</a>.</p></td></tr><tr><td><p>FLEX_DATASOURCE_CONTROL_NODE_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Enable configuration caching in Redis shared storage for Connected Mode replicas. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-conn-replica-caching">Configuring Flex Gateway Configuration Caching in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SERVICE_ENVOY_DRAIN_TIME</p></td><td><p><code>25</code></p></td><td><p>Drain period in seconds during shutdown before Flex Gateway exits gracefully. For more information, see <a href="https://docs.mulesoft.com/gateway/1.12/flex-local-monitor">Monitoring in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_SYNC_DEBOUNCE_TIME</p></td><td><p>"5s"</p></td><td><p>Specifies the amount of time to wait after detecting a configuration change before applying it. This prevents excessive reloading during rapid successive changes. The value must be a valid duration string, such as <code>"5s"</code> or <code>"500ms"</code>.</p></td></tr><tr><td><p>FLEX_LOG_LEVEL</p></td><td><p><code>4</code> (INFO)</p></td><td><p>Sets the logging level for Flex Gateway. For the environment variable configuration of log level, you specify a number that corresponds to the log level. Supported values are NONE:`-1`, FATAL:`0`, ERROR:`1`, WARN:`2`, INFO:`4`, DEBUG:`8`, and TRACE:`16`.</p></td></tr><tr><td><p>FLEX_CONFIG</p></td><td><p>N/A</p></td><td><p>Provides Flex Gateway registration and configuration as a YAML-formatted string. The YAML content must be properly escaped to preserve special characters. Provide your registration and configuration as a string if deploying environments where file mounting isn’t practical, such as Amazon ECS or Azure Container Apps.</p></td></tr></tbody></table>

<!-- document id=5d00c3208f2defb94d238d9f12a95497fcdf68387ed1808ef4db1b1722d031dd url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-k8-node-affinity-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configure Node Selection for Flex Gateway Deployments on Kubernetes (Node Affinity)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway is often critical to the performance and security of a cluster, so it is important to
host it on a specialized node that meets specific requirements, instead of using the nodes that host
other deployments.

To enable the Kubernetes scheduler to select a suitable host node for a Pod that contains Flex
Gateway, you can set custom node affinity rules in a YAML configuration file that incorporates the
Pod’s requirements into a Helm chart for your Flex Gateway deployment. For more information about
node affinity, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity).

The high-level tasks for configuring node affinity follow:

1.  Finding or creating the node labels to use when defining node affinity rules and conditions (see
    [List and Create Node Labels](#list_add_labels)).

2.  Specifying requirements and preferences in a YAML configuration file for a node that hosts a Pod
    with a containerized Flex Gateway application (see
    [Configure Rules for Matching a Node to a Pod for a Flex Gateway Container](#set_node_affinity)).

3.  Upgrading your Helm chart with the YAML configuration (see
    [Upgrade the Helm Chart](#upgrade_helm_chart)).

## Before You Begin

Meet the minimum Kubernetes and Helm version requirements described in the
[software requirements](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites#software-requirements).

## List and Create Node Labels

Each node affinity rule requires the key of a node label and one or more of the label’s values. You
can use existing node labels or create new ones. A node label is defined as a key-value pair.

- To list a cluster’s nodes and node labels, run:

  ```kubernetes
  kubectl get nodes --show-labels
  ```

- To create a label for a node in your cluster, run:

  ```kubernetes
  kubectl label nodes <node-name> <label-key>=<label-value>
  ```

For related Kubernetes documentation, see
[Add a Label to a Node](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node).

## Configure Rules for Matching a Node to a Pod for a Flex Gateway Container

The Kubernetes scheduler can use node affinity rules to match nodes to Pods. The matching process
enables the scheduler to select the node into which a Pod is deployed.

Configure node affinity rules as required, preferred, or both:

- `requiredDuringSchedulingIgnoredDuringExecution`: The node must match all node affinity rules
  configured for a Pod when the Kubernetes scheduler applies this type of matching. Otherwise, the
  deployment fails.

- `preferredDuringSchedulingIgnoredDuringExecution`: Based on weighted preferences set for a Pod,
  the Kubernetes scheduler selects the best matching node. The scheduler must select a node, so if
  no node matches any of the preferences, the scheduler selects a node that does not match.

For guidance, see the following configuration options:

- [Configure a Required Node Matching Rule for a Pod Containing Flex Gateway](#required_node_matching)

- [Configure a Preferred Node Matching Rule for a Pod Containing Flex Gateway](#preferred_node_matching)

- [Configure Required and Preferred Node Matching Rules for a Pod Containing Flex Gateway](#mixed_node_matching)

### Configure a Required Node Matching Rule for a Pod Containing Flex Gateway

In required node matching, the node must meet all node affinity rules configured for a Pod.
Otherwise, the deployment fails.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Flex Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      # - Add any other required conditions.
```

You can add as many values and conditions as the node requires.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure a Preferred Node Matching Rule for a Pod Containing Flex Gateway

In preferred node matching, the Kubernetes scheduler selects a node based on weighted preferences.
The scheduler must select a node, so if no node matches any preferences, the scheduler selects a
node that does not match.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Flex Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
 nodeAffinity:
   preferredDuringSchedulingIgnoredDuringExecution:
   - weight: <integer-x>
     preference:
       matchExpressions:
       - key: <node-label-key1>
         operator: <operator>
         values:
         - <node-label-value>
       # - Add any other values.
    - weight: <integer-y>
      preference:
        matchExpressions:
        - key: <node-label-key2>
          operator: <operator>
          values:
          - <node-label-value>
        # - Add any other node label values.
      # - Add any other preferred conditions.
  # - Any any more preferred rules.
```

You can add any number of preferred values, conditions, and rules.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure Required and Preferred Node Matching Rules for a Pod Containing Flex Gateway

You can configure both types of node affinity (required and preferred) in the same YAML file.

The example combines the settings from
[Configure a Required Node Matching Rule for a Pod Containing Flex Gateway](#required_node_matching)
and
[Configure a Preferred Node Matching Rule for a Pod Containing Flex Gateway](#preferred_node_matching).

Configure a node affinity rule in the YAML configuration file for a Pod that contains Flex Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
    # - Add any other conditions.
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: <integer-x>
        preference:
          matchExpressions:
            - key: <node-label-key1>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      - weight: <integer-y>
        preference:
          matchExpressions:
            - key: <node-label-key2>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
        # - Add any other preferred conditions.
    # - Any any other preferred rules.
```

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

## Upgrade the Helm Chart

After adding the node affinity settings to your YAML configuration file, incorporate the file into
the Helm chart for a Flex Gateway deployment so that the Kubernetes scheduler can use the setting.

Use a `helm` command to incorporate the node affinity settings from your YAML configuration file
into a Helm chart. The command to use depends on whether Flex Gateway is installed:

- If you are installing Flex Gateway for the first time, use this command to set all values in the
  chart:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  -f <path-to-yaml-file> \
  --set-file registration.content=<path-to-registration>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

- If Flex Gateway is installed already, use this command to reuse the chart’s existing configuration
  and set the node affinity configuration:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  --reuse-values -f <path-to-yaml-file>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

For information about the Helm command, see [Helm Upgrade](https://helm.sh/docs/helm/helm_upgrade).

<!-- document id=07893f77f9ccc9c1ab955b1a0ae694a7b7514da4a6c1c8e1bd814afce28437d5 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-k8-node-affinity-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configure Node Selection for Flex Gateway Deployments on Kubernetes (Node Affinity)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway is often critical to the performance and security of a cluster, so it is important to
host it on a specialized node that meets specific requirements, instead of using the nodes that host
other deployments.

To enable the Kubernetes scheduler to select a suitable host node for a Pod that contains Flex
Gateway, you can set custom node affinity rules in a YAML configuration file that incorporates the
Pod’s requirements into a Helm chart for your Flex Gateway deployment. For more information about
node affinity, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity).

The high-level tasks for configuring node affinity follow:

1.  Finding or creating the node labels to use when defining node affinity rules and conditions (see
    [List and Create Node Labels](#list_add_labels)).

2.  Specifying requirements and preferences in a YAML configuration file for a node that hosts a Pod
    with a containerized Flex Gateway application (see
    [Configure Rules for Matching a Node to a Pod for a Flex Gateway Container](#set_node_affinity)).

3.  Upgrading your Helm chart with the YAML configuration (see
    [Upgrade the Helm Chart](#upgrade_helm_chart)).

## Before You Begin

Meet the minimum Kubernetes and Helm version requirements described in the
[software requirements](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites#software-requirements).

## List and Create Node Labels

Each node affinity rule requires the key of a node label and one or more of the label’s values. You
can use existing node labels or create new ones. A node label is defined as a key-value pair.

- To list a cluster’s nodes and node labels, run:

  ```kubernetes
  kubectl get nodes --show-labels
  ```

- To create a label for a node in your cluster, run:

  ```kubernetes
  kubectl label nodes <node-name> <label-key>=<label-value>
  ```

For related Kubernetes documentation, see
[Add a Label to a Node](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node).

## Configure Rules for Matching a Node to a Pod for a Flex Gateway Container

The Kubernetes scheduler can use node affinity rules to match nodes to Pods. The matching process
enables the scheduler to select the node into which a Pod is deployed.

Configure node affinity rules as required, preferred, or both:

- `requiredDuringSchedulingIgnoredDuringExecution`: The node must match all node affinity rules
  configured for a Pod when the Kubernetes scheduler applies this type of matching. Otherwise, the
  deployment fails.

- `preferredDuringSchedulingIgnoredDuringExecution`: Based on weighted preferences set for a Pod,
  the Kubernetes scheduler selects the best matching node. The scheduler must select a node, so if
  no node matches any of the preferences, the scheduler selects a node that does not match.

For guidance, see the following configuration options:

- [Configure a Required Node Matching Rule for a Pod Containing Flex Gateway](#required_node_matching)

- [Configure a Preferred Node Matching Rule for a Pod Containing Flex Gateway](#preferred_node_matching)

- [Configure Required and Preferred Node Matching Rules for a Pod Containing Flex Gateway](#mixed_node_matching)

### Configure a Required Node Matching Rule for a Pod Containing Flex Gateway

In required node matching, the node must meet all node affinity rules configured for a Pod.
Otherwise, the deployment fails.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Flex Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      # - Add any other required conditions.
```

You can add as many values and conditions as the node requires.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure a Preferred Node Matching Rule for a Pod Containing Flex Gateway

In preferred node matching, the Kubernetes scheduler selects a node based on weighted preferences.
The scheduler must select a node, so if no node matches any preferences, the scheduler selects a
node that does not match.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Flex Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
 nodeAffinity:
   preferredDuringSchedulingIgnoredDuringExecution:
   - weight: <integer-x>
     preference:
       matchExpressions:
       - key: <node-label-key1>
         operator: <operator>
         values:
         - <node-label-value>
       # - Add any other values.
    - weight: <integer-y>
      preference:
        matchExpressions:
        - key: <node-label-key2>
          operator: <operator>
          values:
          - <node-label-value>
        # - Add any other node label values.
      # - Add any other preferred conditions.
  # - Any any more preferred rules.
```

You can add any number of preferred values, conditions, and rules.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure Required and Preferred Node Matching Rules for a Pod Containing Flex Gateway

You can configure both types of node affinity (required and preferred) in the same YAML file.

The example combines the settings from
[Configure a Required Node Matching Rule for a Pod Containing Flex Gateway](#required_node_matching)
and
[Configure a Preferred Node Matching Rule for a Pod Containing Flex Gateway](#preferred_node_matching).

Configure a node affinity rule in the YAML configuration file for a Pod that contains Flex Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
    # - Add any other conditions.
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: <integer-x>
        preference:
          matchExpressions:
            - key: <node-label-key1>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      - weight: <integer-y>
        preference:
          matchExpressions:
            - key: <node-label-key2>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
        # - Add any other preferred conditions.
    # - Any any other preferred rules.
```

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

## Upgrade the Helm Chart

After adding the node affinity settings to your YAML configuration file, incorporate the file into
the Helm chart for a Flex Gateway deployment so that the Kubernetes scheduler can use the setting.

Use a `helm` command to incorporate the node affinity settings from your YAML configuration file
into a Helm chart. The command to use depends on whether Flex Gateway is installed:

- If you are installing Flex Gateway for the first time, use this command to set all values in the
  chart:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  -f <path-to-yaml-file> \
  --set-file registration.content=<path-to-registration>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

- If Flex Gateway is installed already, use this command to reuse the chart’s existing configuration
  and set the node affinity configuration:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  --reuse-values -f <path-to-yaml-file>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

For information about the Helm command, see [Helm Upgrade](https://helm.sh/docs/helm/helm_upgrade).

<!-- document id=1b3ae0668399b375dc3ac775bfc8f5329b401ff358d8faa1942ce4e6ee106377 url=/mulesoft/current/en-us/gateway/1.13/gateway-k8-node-affinity-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Node Selection for Omni Gateway Deployments on Kubernetes (Node Affinity)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway is often critical to the performance and security of a cluster, so it is important to
host it on a specialized node that meets specific requirements, instead of using the nodes that host
other deployments.

To enable the Kubernetes scheduler to select a suitable host node for a Pod that contains Omni
Gateway, you can set custom node affinity rules in a YAML configuration file that incorporates the
Pod’s requirements into a Helm chart for your Omni Gateway deployment. For more information about
node affinity, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity).

The high-level tasks for configuring node affinity follow:

1.  Finding or creating the node labels to use when defining node affinity rules and conditions (see
    [List and Create Node Labels](#list_add_labels)).

2.  Specifying requirements and preferences in a YAML configuration file for a node that hosts a Pod
    with a containerized Omni Gateway application (see
    [Configure Rules for Matching a Node to a Pod for an Omni Gateway Container](#set_node_affinity)).

3.  Upgrading your Helm chart with the YAML configuration (see
    [Upgrade the Helm Chart](#upgrade_helm_chart)).

## Before You Begin

Meet the minimum Kubernetes and Helm version requirements described in the
[software requirements](https://docs.mulesoft.com/gateway/1.13/review-prerequisites#software-requirements).

## List and Create Node Labels

Each node affinity rule requires the key of a node label and one or more of the label’s values. You
can use existing node labels or create new ones. A node label is defined as a key-value pair.

- To list a cluster’s nodes and node labels, run:

  ```kubernetes
  kubectl get nodes --show-labels
  ```

- To create a label for a node in your cluster, run:

  ```kubernetes
  kubectl label nodes <node-name> <label-key>=<label-value>
  ```

For related Kubernetes documentation, see
[Add a Label to a Node](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node).

## Configure Rules for Matching a Node to a Pod for an Omni Gateway Container

The Kubernetes scheduler can use node affinity rules to match nodes to Pods. The matching process
enables the scheduler to select the node into which a Pod is deployed.

Configure node affinity rules as required, preferred, or both:

- `requiredDuringSchedulingIgnoredDuringExecution`: The node must match all node affinity rules
  configured for a Pod when the Kubernetes scheduler applies this type of matching. Otherwise, the
  deployment fails.

- `preferredDuringSchedulingIgnoredDuringExecution`: Based on weighted preferences set for a Pod,
  the Kubernetes scheduler selects the best matching node. The scheduler must select a node, so if
  no node matches any of the preferences, the scheduler selects a node that does not match.

For guidance, see the following configuration options:

- [Configure a Required Node Matching Rule for a Pod Containing Omni Gateway](#required_node_matching)

- [Configure a Preferred Node Matching Rule for a Pod Containing Omni Gateway](#preferred_node_matching)

- [Configure Required and Preferred Node Matching Rules for a Pod Containing Omni Gateway](#mixed_node_matching)

### Configure a Required Node Matching Rule for a Pod Containing Omni Gateway

In required node matching, the node must meet all node affinity rules configured for a Pod.
Otherwise, the deployment fails.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Omni Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      # - Add any other required conditions.
```

You can add as many values and conditions as the node requires.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure a Preferred Node Matching Rule for a Pod Containing Omni Gateway

In preferred node matching, the Kubernetes scheduler selects a node based on weighted preferences.
The scheduler must select a node, so if no node matches any preferences, the scheduler selects a
node that does not match.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Omni Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
 nodeAffinity:
   preferredDuringSchedulingIgnoredDuringExecution:
   - weight: <integer-x>
     preference:
       matchExpressions:
       - key: <node-label-key1>
         operator: <operator>
         values:
         - <node-label-value>
       # - Add any other values.
    - weight: <integer-y>
      preference:
        matchExpressions:
        - key: <node-label-key2>
          operator: <operator>
          values:
          - <node-label-value>
        # - Add any other node label values.
      # - Add any other preferred conditions.
  # - Any any more preferred rules.
```

You can add any number of preferred values, conditions, and rules.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure Required and Preferred Node Matching Rules for a Pod Containing Omni Gateway

You can configure both types of node affinity (required and preferred) in the same YAML file.

The example combines the settings from
[Configure a Required Node Matching Rule for a Pod Containing Omni Gateway](#required_node_matching)
and
[Configure a Preferred Node Matching Rule for a Pod Containing Omni Gateway](#preferred_node_matching).

Configure a node affinity rule in the YAML configuration file for a Pod that contains Omni Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
    # - Add any other conditions.
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: <integer-x>
        preference:
          matchExpressions:
            - key: <node-label-key1>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      - weight: <integer-y>
        preference:
          matchExpressions:
            - key: <node-label-key2>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
        # - Add any other preferred conditions.
    # - Any any other preferred rules.
```

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

## Upgrade the Helm Chart

After adding the node affinity settings to your YAML configuration file, incorporate the file into
the Helm chart for an Omni Gateway deployment so that the Kubernetes scheduler can use the setting.

Use a `helm` command to incorporate the node affinity settings from your YAML configuration file
into a Helm chart. The command to use depends on whether Omni Gateway is installed:

- If you are installing Omni Gateway for the first time, use this command to set all values in the
  chart:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  -f <path-to-yaml-file> \
  --set-file registration.content=<path-to-registration>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

- If Omni Gateway is installed already, use this command to reuse the chart’s existing configuration
  and set the node affinity configuration:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  --reuse-values -f <path-to-yaml-file>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

For information about the Helm command, see [Helm Upgrade](https://helm.sh/docs/helm/helm_upgrade).

<!-- document id=74295454e3d32656233dd19ff1851382d6ee09c12d68bd37aea4a1a02cd887d3 url=/mulesoft/current/en-us/gateway/latest/gateway-k8-node-affinity-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Node Selection for Omni Gateway Deployments on Kubernetes (Node Affinity)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway is often critical to the performance and security of a cluster, so it is important to
host it on a specialized node that meets specific requirements, instead of using the nodes that host
other deployments.

To enable the Kubernetes scheduler to select a suitable host node for a Pod that contains Omni
Gateway, you can set custom node affinity rules in a YAML configuration file that incorporates the
Pod’s requirements into a Helm chart for your Omni Gateway deployment. For more information about
node affinity, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity).

The high-level tasks for configuring node affinity follow:

1.  Finding or creating the node labels to use when defining node affinity rules and conditions (see
    [List and Create Node Labels](#list_add_labels)).

2.  Specifying requirements and preferences in a YAML configuration file for a node that hosts a Pod
    with a containerized Omni Gateway application (see
    [Configure Rules for Matching a Node to a Pod for an Omni Gateway Container](#set_node_affinity)).

3.  Upgrading your Helm chart with the YAML configuration (see
    [Upgrade the Helm Chart](#upgrade_helm_chart)).

## Before You Begin

Meet the minimum Kubernetes and Helm version requirements described in the
[software requirements](https://docs.mulesoft.com/gateway/latest/review-prerequisites#software-requirements).

## List and Create Node Labels

Each node affinity rule requires the key of a node label and one or more of the label’s values. You
can use existing node labels or create new ones. A node label is defined as a key-value pair.

- To list a cluster’s nodes and node labels, run:

  ```kubernetes
  kubectl get nodes --show-labels
  ```

- To create a label for a node in your cluster, run:

  ```kubernetes
  kubectl label nodes <node-name> <label-key>=<label-value>
  ```

For related Kubernetes documentation, see
[Add a Label to a Node](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node).

## Configure Rules for Matching a Node to a Pod for an Omni Gateway Container

The Kubernetes scheduler can use node affinity rules to match nodes to Pods. The matching process
enables the scheduler to select the node into which a Pod is deployed.

Configure node affinity rules as required, preferred, or both:

- `requiredDuringSchedulingIgnoredDuringExecution`: The node must match all node affinity rules
  configured for a Pod when the Kubernetes scheduler applies this type of matching. Otherwise, the
  deployment fails.

- `preferredDuringSchedulingIgnoredDuringExecution`: Based on weighted preferences set for a Pod,
  the Kubernetes scheduler selects the best matching node. The scheduler must select a node, so if
  no node matches any of the preferences, the scheduler selects a node that does not match.

For guidance, see the following configuration options:

- [Configure a Required Node Matching Rule for a Pod Containing Omni Gateway](#required_node_matching)

- [Configure a Preferred Node Matching Rule for a Pod Containing Omni Gateway](#preferred_node_matching)

- [Configure Required and Preferred Node Matching Rules for a Pod Containing Omni Gateway](#mixed_node_matching)

### Configure a Required Node Matching Rule for a Pod Containing Omni Gateway

In required node matching, the node must meet all node affinity rules configured for a Pod.
Otherwise, the deployment fails.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Omni Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      # - Add any other required conditions.
```

You can add as many values and conditions as the node requires.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure a Preferred Node Matching Rule for a Pod Containing Omni Gateway

In preferred node matching, the Kubernetes scheduler selects a node based on weighted preferences.
The scheduler must select a node, so if no node matches any preferences, the scheduler selects a
node that does not match.

Configure a node affinity rule in the YAML configuration file for a Pod that contains Omni Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
 nodeAffinity:
   preferredDuringSchedulingIgnoredDuringExecution:
   - weight: <integer-x>
     preference:
       matchExpressions:
       - key: <node-label-key1>
         operator: <operator>
         values:
         - <node-label-value>
       # - Add any other values.
    - weight: <integer-y>
      preference:
        matchExpressions:
        - key: <node-label-key2>
          operator: <operator>
          values:
          - <node-label-value>
        # - Add any other node label values.
      # - Add any other preferred conditions.
  # - Any any more preferred rules.
```

You can add any number of preferred values, conditions, and rules.

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

### Configure Required and Preferred Node Matching Rules for a Pod Containing Omni Gateway

You can configure both types of node affinity (required and preferred) in the same YAML file.

The example combines the settings from
[Configure a Required Node Matching Rule for a Pod Containing Omni Gateway](#required_node_matching)
and
[Configure a Preferred Node Matching Rule for a Pod Containing Omni Gateway](#preferred_node_matching).

Configure a node affinity rule in the YAML configuration file for a Pod that contains Omni Gateway.
Each condition to a rule requires a node label as a `key`, an operator, and one or more node label
values to accept for a node with that key. For operators, you can use `In`, `NotIn`, `Exists`,
`DoesNotExist`, `Gt`, and `Lt`. In addition, provide a `weight` value between `1` and `100` for each
`preference` so that the Kubernetes scheduler can determine which rules are more important and
select the best matching node. Matching is based on the sum of the weighted preferences that a node
meets. The scheduler selects a node with the greatest total weight over other nodes of lesser
weight.

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <node-label-key>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
    # - Add any other conditions.
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: <integer-x>
        preference:
          matchExpressions:
            - key: <node-label-key1>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
      - weight: <integer-y>
        preference:
          matchExpressions:
            - key: <node-label-key2>
              operator: <operator>
              values:
                - <node-label-value>
          # - Add any other node label values.
        # - Add any other preferred conditions.
    # - Any any other preferred rules.
```

After configuring the YAML configuration file for the Pod, proceed to
[Upgrade the Helm Chart](#upgrade_helm_chart).

## Upgrade the Helm Chart

After adding the node affinity settings to your YAML configuration file, incorporate the file into
the Helm chart for an Omni Gateway deployment so that the Kubernetes scheduler can use the setting.

Use a `helm` command to incorporate the node affinity settings from your YAML configuration file
into a Helm chart. The command to use depends on whether Omni Gateway is installed:

- If you are installing Omni Gateway for the first time, use this command to set all values in the
  chart:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  -f <path-to-yaml-file> \
  --set-file registration.content=<path-to-registration>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

- If Omni Gateway is installed already, use this command to reuse the chart’s existing configuration
  and set the node affinity configuration:

  ```kubernetes
  helm -n gateway upgrade -i --create-namespace \
  --wait ingress flex-gateway/flex-gateway \
  --reuse-values -f <path-to-yaml-file>
  ```

  Notice that the command passes the YAML file with the node affinity rules.

For information about the Helm command, see [Helm Upgrade](https://helm.sh/docs/helm/helm_upgrade).

<!-- document id=170a2343ac0d41c4eebcc432039c41bd5d94b6801c45959e7ec6a4e9fd20a261 url=/mulesoft/current/en-us/gateway/1.13/gateway-k8-ingress-class.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Omni Gateway as an Ingress Controller in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Kubernetes deployments in Local Mode, Omni Gateway typically acts as an ingress controller that
manages external access to your Kubernetes cluster.

By default, Omni Gateways deployed on Kubernetes in Local Mode are configured as ingress controllers
and can consume `Ingress` resources. The ingress controller configuration is defined in the
`IngressClass` resource parameters in the Omni Gateway Helm chart.

In Kubernetes terminology, `IngressClass` resources configure a gateway as an ingress controller,
and `Ingress` resources configure a routing between the ingress controller and the Kubernetes
services it controls. For a detailed explanation of Kubernetes `IngressClass` resources and
`Ingress` resources, see
[Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

In the Helm chart, you can edit the `IngressClass` configuration or disable the ingress controller
functionality.

## Before You Begin

1.  [Download Omni Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/install#kubernetes).

2.  [Register and Run Omni Gateway in a Kubernetes Cluster in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

## Ingress Class Parameters

The Helm chart includes the following default `IngressClass` parameters and values:

```helm
ingressClass.enabled: true
ingressClass.name: "{releaseName}-{namespace}"
ingressClass.setAsDefault: false
```

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td><td><p>Possible values</p></td></tr><tr><td><p><code>ingressClass.enabled</code></p></td><td><p>Enables Omni Gateway as an <code>IngressClass</code> resource</p></td><td><p><code>true</code> or <code>false</code></p></td></tr><tr><td><p><code>ingressClass.name</code></p></td><td><p>The name of the <code>IngressClass</code></p></td><td><p>Any string</p></td></tr><tr><td><p><code>ingressClass.setAsDefault</code></p></td><td><p>Sets Omni Gateway as the default <code>IngressClass</code></p></td><td><p><code>true</code> or <code>false</code></p></td></tr></tbody></table>

Setting `ingressClass.setAsDefault: true` defines the Omni Gateway instance as the default
`IngressClass` resource for the cluster. The default `IngressClass` is the default ingress
controller for all `Ingress` resources you create in the cluster.

If there is no default `IngressClass`, or if the default `IngressClass` resource shouldn’t be the
ingress controller for a specific resource, you must manually define the ingress controller in the
`Ingress` resource.

You can modify the default `IngressClass` parameters during or after the initial installation of the
Helm chart. For more information about how to modify a Helm chart, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings)

## Creating Ingress Resources

After you [install a Helm chart into a namespace](https://docs.mulesoft.com/gateway/1.13/local-reg-run-up#kubernetes), you can verify your
new `IngressClass` resource by running the following command:

```helm
kubectl get ingressclasses
```

To create an ingress routing:

1.  [Publish an API in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-publish-simple-api#kubernetes).

2.  Define the new API as a Kubernetes Service.  
    For more information about Kubernetes Service definitions, see
    [Defining a Service](https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service).

3.  Using `kubectl apply`, create an `Ingress` resource to define routing rules between the
    `IngressClass` Omni Gateway and the new Kubernetes Service:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: <metadata-name>
      annotations:
        flex-gateway.ingress.kubernetes.io/api-instance: <api-instance-name>.<namespace>
    spec:
      ingressClassName: <ingress-class-name>
      rules:
      - http: ...
    EOF
    ```

    The `annotations` field value must match the API instance name and namespace specified when the
    API was defined.

    Omit the `ingressClassName` field if the gateway instance is configured as the default ingress
    controller.

    For more information about `Ingress` resources, see
    [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

## See Also

- [Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management)

<!-- document id=1d06618f4c03870471c137c994b495189aa960fb3f0ee22e0e4ac849c09c3b93 url=/mulesoft/current/en-us/gateway/latest/gateway-k8-ingress-class.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Omni Gateway as an Ingress Controller in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Kubernetes deployments in Local Mode, Omni Gateway typically acts as an ingress controller that
manages external access to your Kubernetes cluster.

By default, Omni Gateways deployed on Kubernetes in Local Mode are configured as ingress controllers
and can consume `Ingress` resources. The ingress controller configuration is defined in the
`IngressClass` resource parameters in the Omni Gateway Helm chart.

In Kubernetes terminology, `IngressClass` resources configure a gateway as an ingress controller,
and `Ingress` resources configure a routing between the ingress controller and the Kubernetes
services it controls. For a detailed explanation of Kubernetes `IngressClass` resources and
`Ingress` resources, see
[Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

In the Helm chart, you can edit the `IngressClass` configuration or disable the ingress controller
functionality.

## Before You Begin

1.  [Download Omni Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/install#kubernetes).

2.  [Register and Run Omni Gateway in a Kubernetes Cluster in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

## Ingress Class Parameters

The Helm chart includes the following default `IngressClass` parameters and values:

```helm
ingressClass.enabled: true
ingressClass.name: "{releaseName}-{namespace}"
ingressClass.setAsDefault: false
```

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td><td><p>Possible values</p></td></tr><tr><td><p><code>ingressClass.enabled</code></p></td><td><p>Enables Omni Gateway as an <code>IngressClass</code> resource</p></td><td><p><code>true</code> or <code>false</code></p></td></tr><tr><td><p><code>ingressClass.name</code></p></td><td><p>The name of the <code>IngressClass</code></p></td><td><p>Any string</p></td></tr><tr><td><p><code>ingressClass.setAsDefault</code></p></td><td><p>Sets Omni Gateway as the default <code>IngressClass</code></p></td><td><p><code>true</code> or <code>false</code></p></td></tr></tbody></table>

Setting `ingressClass.setAsDefault: true` defines the Omni Gateway instance as the default
`IngressClass` resource for the cluster. The default `IngressClass` is the default ingress
controller for all `Ingress` resources you create in the cluster.

If there is no default `IngressClass`, or if the default `IngressClass` resource shouldn’t be the
ingress controller for a specific resource, you must manually define the ingress controller in the
`Ingress` resource.

You can modify the default `IngressClass` parameters during or after the initial installation of the
Helm chart. For more information about how to modify a Helm chart, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings)

## Creating Ingress Resources

After you [install a Helm chart into a namespace](https://docs.mulesoft.com/gateway/latest/local-reg-run-up#kubernetes), you can verify your
new `IngressClass` resource by running the following command:

```helm
kubectl get ingressclasses
```

To create an ingress routing:

1.  [Publish an API in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-simple-api#kubernetes).

2.  Define the new API as a Kubernetes Service.  
    For more information about Kubernetes Service definitions, see
    [Defining a Service](https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service).

3.  Using `kubectl apply`, create an `Ingress` resource to define routing rules between the
    `IngressClass` Omni Gateway and the new Kubernetes Service:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: <metadata-name>
      annotations:
        flex-gateway.ingress.kubernetes.io/api-instance: <api-instance-name>.<namespace>
    spec:
      ingressClassName: <ingress-class-name>
      rules:
      - http: ...
    EOF
    ```

    The `annotations` field value must match the API instance name and namespace specified when the
    API was defined.

    Omit the `ingressClassName` field if the gateway instance is configured as the default ingress
    controller.

    For more information about `Ingress` resources, see
    [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).

## See Also

- [Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management)

<!-- document id=77325af15c2ffb2469ab9c748a3e5ab25fe23c095b73743d62a0aa9b59783f2d url=/mulesoft/current/en-us/gateway/1.13/conn-env-variables.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Omni Gateway Environment Variables in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides these environment variables to configure your gateway:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p>FLEX_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a connection can be idle before it times out. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_STREAM_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>300</code></p></td><td><p>Maximum number of seconds a stream can remain idle without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni Gateway to upstream service) direction. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a stream between Omni Gateway and the upstream service can remain idle between requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_RESPONSE_TIMEOUT_SECONDS</p></td><td><p><code>15</code></p></td><td><p>Maximum number of seconds an Omni Gateway waits for a response from an upstream service. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_ENVOY_HEADERS_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Allows (<code>true</code>) or removes (<code>false</code>) Envoy headers from requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_REWRITE_HOST_HEADER</p></td><td><p><code>true</code></p></td><td><p>Rewrite HTTP Host header to match upstream.</p></td></tr><tr><td><p>FLEX_REMOVE_SERVER_HEADER</p></td><td><p><code>false</code></p></td><td><p>Removes the <code>Server</code> HTTP response header from outbound responses when set to <code>true</code>. Set to <code>true</code> to reduce exposure of server implementation details for security or compliance purposes.</p></td></tr><tr><td><p>FLEX_HEADER_RAW_VALUE_ENABLE</p></td><td><p>`tru`e</p></td><td><p>Controls header encoding for external authorization. Set to <code>false</code> to send headers encoded in UTF-8. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/policies-included-external-authorization">External Authorization Policy</a>.</p></td></tr><tr><td><p>FLEX_FORWARD_CLIENT_CERT_DETAILS</p></td><td><p><code>SANITIZE</code></p></td><td><p>Controls how the <code>x-forwarded-client-cert</code> (XFCC) HTTP header is handled. Supported values are <code>SANITIZE</code>, <code>FORWARD_ONLY</code>, <code>APPEND_FORWARD</code>, <code>SANITIZE_SET</code>, and <code>ALWAYS_FORWARD_ONLY</code>. For more information, see <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails">HTTP connection manager (proto)</a> in the Envoy documentation.</p></td></tr><tr><td><p>FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES</p></td><td><p><code>1048576</code> (1 MB)</p></td><td><p>Maximum size, in bytes, of read and write buffers for new connections. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_DATASOURCE_CONTROL_NODE_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Enable configuration caching in Redis shared storage for Connected Mode replicas. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/conn-replica-caching">Configuring Omni Gateway Configuration Caching in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SERVICE_ENVOY_DRAIN_TIME</p></td><td><p><code>25</code></p></td><td><p>Drain period in seconds during shutdown before Omni Gateway exits gracefully. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/conn-monitor">Monitoring in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SYNC_DEBOUNCE_TIME</p></td><td><p>"5s"</p></td><td><p>Specifies the amount of time to wait after detecting a configuration change before applying it. This prevents excessive reloading during rapid successive changes. The value must be a valid duration string, such as <code>"5s"</code> or <code>"500ms"</code>.</p></td></tr><tr><td><p>FLEX_LOG_LEVEL</p></td><td><p><code>4</code> (INFO)</p></td><td><p>Sets the logging level for Omni Gateway. For the environment variable configuration of log level, you specify a number that corresponds to the log level. Supported values are NONE:`-1`, FATAL:`0`, ERROR:`1`, WARN:`2`, INFO:`4`, DEBUG:`8`, and TRACE:`16`.</p></td></tr><tr><td><p>FLEX_CONFIG</p></td><td><p>N/A</p></td><td><p>Provides Omni Gateway registration and configuration as a YAML-formatted string. The YAML content must be properly escaped to preserve special characters. Provide your registration and configuration as a string if deploying environments where file mounting isn’t practical, such as Amazon ECS or Azure Container Apps.</p></td></tr></tbody></table>

<!-- document id=8b227efa00666ec36bc28e2f73c97c6f1aa6e103cbfd18c49c5da98f7bc06e1b url=/mulesoft/current/en-us/gateway/latest/conn-env-variables.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Omni Gateway Environment Variables in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides these environment variables to configure your gateway:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p>FLEX_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a connection can be idle before it times out. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_STREAM_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>300</code></p></td><td><p>Maximum number of seconds a stream can remain idle without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni Gateway to upstream service) direction. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a stream between Omni Gateway and the upstream service can remain idle between requests. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_RESPONSE_TIMEOUT_SECONDS</p></td><td><p><code>15</code></p></td><td><p>Maximum number of seconds an Omni Gateway waits for a response from an upstream service. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/conn-timeout">Configuring Timeouts in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_ENVOY_HEADERS_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Allows (<code>true</code>) or removes (<code>false</code>) Envoy headers from requests. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_REWRITE_HOST_HEADER</p></td><td><p><code>true</code></p></td><td><p>Rewrite HTTP Host header to match upstream.</p></td></tr><tr><td><p>FLEX_REMOVE_SERVER_HEADER</p></td><td><p><code>false</code></p></td><td><p>Removes the <code>Server</code> HTTP response header from outbound responses when set to <code>true</code>. Set to <code>true</code> to reduce exposure of server implementation details for security or compliance purposes.</p></td></tr><tr><td><p>FLEX_HEADER_RAW_VALUE_ENABLE</p></td><td><p>`tru`e</p></td><td><p>Controls header encoding for external authorization. Set to <code>false</code> to send headers encoded in UTF-8. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/policies-included-external-authorization">External Authorization Policy</a>.</p></td></tr><tr><td><p>FLEX_FORWARD_CLIENT_CERT_DETAILS</p></td><td><p><code>SANITIZE</code></p></td><td><p>Controls how the <code>x-forwarded-client-cert</code> (XFCC) HTTP header is handled. Supported values are <code>SANITIZE</code>, <code>FORWARD_ONLY</code>, <code>APPEND_FORWARD</code>, <code>SANITIZE_SET</code>, and <code>ALWAYS_FORWARD_ONLY</code>. For more information, see <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails">HTTP connection manager (proto)</a> in the Envoy documentation.</p></td></tr><tr><td><p>FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES</p></td><td><p><code>1048576</code> (1 MB)</p></td><td><p>Maximum size, in bytes, of read and write buffers for new connections. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_DATASOURCE_CONTROL_NODE_ENABLED</p></td><td><p><code>true</code></p></td><td><p>Enable configuration caching in Redis shared storage for Connected Mode replicas. This variable is enabled by default. To disable configuration caching, set this variable to <code>false</code>. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/conn-replica-caching">Configuring Omni Gateway Configuration Caching in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SERVICE_ENVOY_DRAIN_TIME</p></td><td><p><code>25</code></p></td><td><p>Drain period in seconds during shutdown before Omni Gateway exits gracefully. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/conn-monitor">Monitoring in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SYNC_DEBOUNCE_TIME</p></td><td><p>"5s"</p></td><td><p>Specifies the amount of time to wait after detecting a configuration change before applying it. This prevents excessive reloading during rapid successive changes. The value must be a valid duration string, such as <code>"5s"</code> or <code>"500ms"</code>.</p></td></tr><tr><td><p>FLEX_DNS_REFRESH_RATE</p></td><td><p><code>5s</code></p></td><td><p>Sets how often Omni Gateway refreshes DNS for upstream service clusters. The value is a duration string that is clamped between <code>5s</code> and <code>60s</code>. Values below the minimum or above the maximum are adjusted to the nearest bound.</p></td></tr><tr><td><p>FLEX_LOG_LEVEL</p></td><td><p><code>4</code> (INFO)</p></td><td><p>Sets the logging level for Omni Gateway. For the environment variable configuration of log level, you specify a number that corresponds to the log level. Supported values are NONE:`-1`, FATAL:`0`, ERROR:`1`, WARN:`2`, INFO:`4`, DEBUG:`8`, and TRACE:`16`.</p></td></tr><tr><td><p>FLEX_CONFIG</p></td><td><p>N/A</p></td><td><p>Provides Omni Gateway registration and configuration as a YAML-formatted string. The YAML content must be properly escaped to preserve special characters. Provide your registration and configuration as a string if deploying environments where file mounting isn’t practical, such as Amazon ECS or Azure Container Apps.</p></td></tr></tbody></table>

## Configure Global and Routing Settings in Runtime Manager

Configure these variables from Runtime Manager:

- **Global connection buffer limit** (`FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES`)

- **Rewrite Host Header** (`FLEX_REWRITE_HOST_HEADER`)

If you configure a setting in both places, the Runtime Manager value takes precedence over the
environment variable.

To configure these settings in Runtime Manager:

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**, and then select your gateway.

3.  Open **Runtime Configurations**.

4.  Edit the variables and apply your changes.

## Environment Variable Synchronization

Runtime Manager runtime configurations and environment variables don’t synchronize in either
direction:

- Omni Gateway reads `FLEX_*` environment variables only when the pod starts, and uses them to set
  the initial value. Applying a change in Runtime Manager doesn’t update the environment variable,
  so commands such as `kubectl exec <pod> — env` continue to show the original value after a
  successful change.

- Changing an environment variable on the pod isn’t reflected in Runtime Manager.

To verify the effective value, don’t check the pod environment. Instead, run `flexctl dump` and open
`resources/Configuration.json` in the extracted ZIP file.

If the setting is present, that value is in effect. If the setting is absent, the environment
variable value or built-in default applies. For more information, see
[Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/latest/troubleshoot-admin-api).

<!-- document id=2703fc5caa1f9d81ae6030f4ffa44e3aa8498014f6fadded736245bb482c1cc2 url=/mulesoft/current/en-us/gateway/1.13/local-env-variables.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Omni Gateway Environment Variables in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides these environment variables to configure your gateway:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p>FLEX_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a connection can be idle before it times out. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_STREAM_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>300</code></p></td><td><p>Maximum number of seconds a stream can remain idle without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni Gateway to upstream service) direction. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a stream between Omni Gateway and the upstream service can remain idle between requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_RESPONSE_TIMEOUT_SECONDS</p></td><td><p><code>15</code></p></td><td><p>Maximum number of seconds an Omni Gateway waits for a response from an upstream service. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_ENVOY_HEADERS_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Allows (<code>true</code>) or removes (<code>false</code>) Envoy headers from requests. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_REWRITE_HOST_HEADER</p></td><td><p><code>true</code></p></td><td><p>Rewrite HTTP Host header to match upstream.</p></td></tr><tr><td><p>FLEX_REMOVE_SERVER_HEADER</p></td><td><p><code>false</code></p></td><td><p>Removes the <code>Server</code> HTTP response header from outbound responses when set to <code>true</code>. Set to <code>true</code> to reduce exposure of server implementation details for security or compliance purposes.</p></td></tr><tr><td><p>FLEX_HEADER_RAW_VALUE_ENABLE</p></td><td><p>`tru`e</p></td><td><p>Controls header encoding for external authorization. Set to <code>false</code> to send headers encoded in UTF-8. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/policies-included-external-authorization">External Authorization Policy</a>.</p></td></tr><tr><td><p>FLEX_FORWARD_CLIENT_CERT_DETAILS</p></td><td><p><code>SANITIZE</code></p></td><td><p>Controls how the <code>x-forwarded-client-cert</code> (XFCC) HTTP header is handled. Supported values are <code>SANITIZE</code>, <code>FORWARD_ONLY</code>, <code>APPEND_FORWARD</code>, <code>SANITIZE_SET</code>, and <code>ALWAYS_FORWARD_ONLY</code>. For more information, see <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails">HTTP connection manager (proto)</a> in the Envoy documentation.</p></td></tr><tr><td><p>FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES</p></td><td><p><code>1048576</code> (1 MB)</p></td><td><p>Maximum size, in bytes, of read and write buffers for new connections. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_DATASOURCE_CONTROL_NODE_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Enable configuration caching in Redis shared storage for Connected Mode replicas. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/conn-replica-caching">Configuring Omni Gateway Configuration Caching in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SERVICE_ENVOY_DRAIN_TIME</p></td><td><p><code>25</code></p></td><td><p>Drain period in seconds during shutdown before Omni Gateway exits gracefully. For more information, see <a href="https://docs.mulesoft.com/gateway/1.13/local-monitor">Monitoring in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_SYNC_DEBOUNCE_TIME</p></td><td><p>"5s"</p></td><td><p>Specifies the amount of time to wait after detecting a configuration change before applying it. This prevents excessive reloading during rapid successive changes. The value must be a valid duration string, such as <code>"5s"</code> or <code>"500ms"</code>.</p></td></tr><tr><td><p>FLEX_LOG_LEVEL</p></td><td><p><code>4</code> (INFO)</p></td><td><p>Sets the logging level for Omni Gateway. For the environment variable configuration of log level, you specify a number that corresponds to the log level. Supported values are NONE:`-1`, FATAL:`0`, ERROR:`1`, WARN:`2`, INFO:`4`, DEBUG:`8`, and TRACE:`16`.</p></td></tr><tr><td><p>FLEX_CONFIG</p></td><td><p>N/A</p></td><td><p>Provides Omni Gateway registration and configuration as a YAML-formatted string. The YAML content must be properly escaped to preserve special characters. Provide your registration and configuration as a string if deploying environments where file mounting isn’t practical, such as Amazon ECS or Azure Container Apps.</p></td></tr></tbody></table>

<!-- document id=8d6efa52ba61ef4bb1b15d3a0db22d60d3df6f2962b0324121c211b46571267f url=/mulesoft/current/en-us/gateway/latest/local-env-variables.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Omni Gateway Environment Variables in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides these environment variables to configure your gateway:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p>FLEX_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a connection can be idle before it times out. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_STREAM_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>300</code></p></td><td><p>Maximum number of seconds a stream can remain idle without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni Gateway to upstream service) direction. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_CONNECTION_IDLE_TIMEOUT_SECONDS</p></td><td><p><code>60</code></p></td><td><p>Maximum number of seconds a stream between Omni Gateway and the upstream service can remain idle between requests. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_UPSTREAM_RESPONSE_TIMEOUT_SECONDS</p></td><td><p><code>15</code></p></td><td><p>Maximum number of seconds an Omni Gateway waits for a response from an upstream service. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/local-timeout">Configuring Timeouts in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_ENVOY_HEADERS_ENABLED</p></td><td><p><code>false</code></p></td><td><p>Allows (<code>true</code>) or removes (<code>false</code>) Envoy headers from requests. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_REWRITE_HOST_HEADER</p></td><td><p><code>true</code></p></td><td><p>Rewrite HTTP Host header to match upstream.</p></td></tr><tr><td><p>FLEX_REMOVE_SERVER_HEADER</p></td><td><p><code>false</code></p></td><td><p>Removes the <code>Server</code> HTTP response header from outbound responses when set to <code>true</code>. Set to <code>true</code> to reduce exposure of server implementation details for security or compliance purposes.</p></td></tr><tr><td><p>FLEX_HEADER_RAW_VALUE_ENABLE</p></td><td><p>`tru`e</p></td><td><p>Controls header encoding for external authorization. Set to <code>false</code> to send headers encoded in UTF-8. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/policies-included-external-authorization">External Authorization Policy</a>.</p></td></tr><tr><td><p>FLEX_FORWARD_CLIENT_CERT_DETAILS</p></td><td><p><code>SANITIZE</code></p></td><td><p>Controls how the <code>x-forwarded-client-cert</code> (XFCC) HTTP header is handled. Supported values are <code>SANITIZE</code>, <code>FORWARD_ONLY</code>, <code>APPEND_FORWARD</code>, <code>SANITIZE_SET</code>, and <code>ALWAYS_FORWARD_ONLY</code>. For more information, see <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails">HTTP connection manager (proto)</a> in the Envoy documentation.</p></td></tr><tr><td><p>FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES</p></td><td><p><code>1048576</code> (1 MB)</p></td><td><p>Maximum size, in bytes, of read and write buffers for new connections. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/review-prerequisites">Requirements and Limits for Omni Gateway</a>.</p></td></tr><tr><td><p>FLEX_DATASOURCE_CONTROL_NODE_ENABLED</p></td><td><p><code>true</code></p></td><td><p>Enable configuration caching in Redis shared storage for Connected Mode replicas. This variable is enabled by default. To disable configuration caching, set this variable to <code>false</code>. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/conn-replica-caching">Configuring Omni Gateway Configuration Caching in Connected Mode</a>.</p></td></tr><tr><td><p>FLEX_SERVICE_ENVOY_DRAIN_TIME</p></td><td><p><code>25</code></p></td><td><p>Drain period in seconds during shutdown before Omni Gateway exits gracefully. For more information, see <a href="https://docs.mulesoft.com/gateway/latest/local-monitor">Monitoring in Local Mode</a>.</p></td></tr><tr><td><p>FLEX_SYNC_DEBOUNCE_TIME</p></td><td><p>"5s"</p></td><td><p>Specifies the amount of time to wait after detecting a configuration change before applying it. This prevents excessive reloading during rapid successive changes. The value must be a valid duration string, such as <code>"5s"</code> or <code>"500ms"</code>.</p></td></tr><tr><td><p>FLEX_DNS_REFRESH_RATE</p></td><td><p><code>5s</code></p></td><td><p>Sets how often Omni Gateway refreshes DNS for upstream service clusters. The value is a duration string that is clamped between <code>5s</code> and <code>60s</code>. Values below the minimum or above the maximum are adjusted to the nearest bound.</p></td></tr><tr><td><p>FLEX_LOG_LEVEL</p></td><td><p><code>4</code> (INFO)</p></td><td><p>Sets the logging level for Omni Gateway. For the environment variable configuration of log level, you specify a number that corresponds to the log level. Supported values are NONE:`-1`, FATAL:`0`, ERROR:`1`, WARN:`2`, INFO:`4`, DEBUG:`8`, and TRACE:`16`.</p></td></tr><tr><td><p>FLEX_CONFIG</p></td><td><p>N/A</p></td><td><p>Provides Omni Gateway registration and configuration as a YAML-formatted string. The YAML content must be properly escaped to preserve special characters. Provide your registration and configuration as a string if deploying environments where file mounting isn’t practical, such as Amazon ECS or Azure Container Apps.</p></td></tr></tbody></table>

> [!NOTE] Omni Gateway reads `FLEX_*` environment variables only when it starts. To verify the
> values the gateway is running with, run `flexctl dump` and open `env/vars.json` in the extracted
> ZIP file. For more information, see [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/latest/troubleshoot-admin-api).

<!-- document id=3ce6249c4b641fa9d88c9598ef77d48dbd4927ecd51769be48146db3660e4beb url=/mulesoft/current/en-us/gateway/1.12/flex-managed-timeout.md -->

---
product: Omni Gateway
version: 1.12
---

# Configure Timeouts for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex
  Gateway to upstream service) direction.

  By default, all Flex Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Flex
  Gateway and the upstream service can remain idle between requests.

  By default, all Flex Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Flex Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Flex
  Gateway.

  By default, all Flex Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts for Managed Flex Gateway via:

- Managed Flex Gateway deployment: Set initial timeout values when you create the gateway.

- Runtime Manager runtime configurations: Applies to all API instances in the gateway after the
  gateway is deployed.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Timeouts During Managed Gateway Deployment

Set timeout values in the deployment flow when you create a Managed Flex Gateway. For the UI steps
and parameter descriptions, see [Deploy a Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-managed-set-up).

## Configure Timeouts in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways**.

3.  Select your Flex Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Timeouts**.

6.  Set values for **Stream Idle Timeout**, **Upstream Connection Idle Timeout**, and **Upstream
    Response Timeout**.

7.  Apply the changes.

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-response-timeout)

<!-- document id=623dae7c102298c4b461910a3a8f63400e7e6925cb21cfbce8cf59349a6f383b url=/mulesoft/current/en-us/gateway/1.13/managed-timeout.md -->

---
product: Omni Gateway
version: 1.13
---

# Configure Timeouts for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni
  Gateway to upstream service) direction.

  By default, all Omni Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Omni
  Gateway and the upstream service can remain idle between requests.

  By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Omni Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Omni
  Gateway.

  By default, all Omni Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts for Managed Omni Gateway via:

- Managed Omni Gateway deployment: Set initial timeout values when you create the gateway.

- Runtime Manager runtime configurations: Applies to all API instances in the gateway after the
  gateway is deployed.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Timeouts During Managed Gateway Deployment

Set timeout values in the deployment flow when you create a Managed Omni Gateway. For the UI steps
and parameter descriptions, see [Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-managed-set-up).

## Configure Timeouts in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Timeouts**.

6.  Set values for **Stream Idle Timeout**, **Upstream Connection Idle Timeout**, and **Upstream
    Response Timeout**.

7.  Apply the changes.

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-response-timeout)

<!-- document id=f5fe258ed5f1c6072fb67609f318813ee6bca85bbf7bb1abe6450008bbb77926 url=/mulesoft/current/en-us/gateway/latest/managed-timeout.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configure Timeouts for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni
  Gateway to upstream service) direction.

  By default, all Omni Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Omni
  Gateway and the upstream service can remain idle between requests.

  By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Omni Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Omni
  Gateway.

  By default, all Omni Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts for Managed Omni Gateway via:

- Managed Omni Gateway deployment: Set initial timeout values when you create the gateway.

- Runtime Manager runtime configurations: Applies to all API instances in the gateway after the
  gateway is deployed.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set,
in this order of precedence:

1.  **Policy**: A policy applied to the API instance.

2.  **Runtime Manager runtime configuration**: Used if no policy value is set.

3.  **Built-in default**: Used if neither of the other values is set. A policy value overrides the
    gateway-level value for the API instance it’s applied to. API instances without the policy use
    the gateway-level value.

## Configure Timeouts During Managed Gateway Deployment

Set timeout values in the deployment flow when you create a Managed Omni Gateway. For the UI steps
and parameter descriptions, see [Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up).

## Configure Timeouts in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Timeouts**.

6.  Set values for **Stream Idle Timeout**, **Upstream Connection Idle Timeout**, and **Upstream
    Response Timeout**.

7.  Apply the changes.

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-included-response-timeout)

<!-- document id=1213470405781111f8e771f9519a801c27aa6bf175e71a02ad89959eaccddf7b url=/mulesoft/current/en-us/gateway/1.12/flex-conn-forward-proxy.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring a Forward Proxy for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Flex Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/1.12/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Flex Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/1.12/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Flex Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Flex
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster

To configure a forward proxy for Flex Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Flex Gateway does not have direct internet access, see
[Forward Proxy Flex Gateway Registration](#proxy-registration).

## Forward Proxy Flex Gateway Registration

If your Flex Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Flex Gateway deployment.

## See also

- [Register and Run Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

<!-- document id=ec4b302f83d84b596f9324f8e63a1f4b9baf372c02341b2ff634cc7b2511d2dc url=/mulesoft/current/en-us/gateway/1.9/flex-conn-forward-proxy.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring a Forward Proxy for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Flex Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/1.9/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Flex Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/1.9/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Flex Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Flex
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster

To configure a forward proxy for Flex Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Flex Gateway does not have direct internet access, see
[Forward Proxy Flex Gateway Registration](#proxy-registration).

## Forward Proxy Flex Gateway Registration

If your Flex Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Flex Gateway deployment.

## See also

- [Register and Run Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

<!-- document id=f47bf20d7d54e16ee7c327bdc8a6a1317879154f0d9235d07d9ec6f2d3d96582 url=/mulesoft/current/en-us/gateway/1.12/flex-local-forward-proxy.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring a Forward Proxy for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Flex Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/1.12/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Flex Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/1.12/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Flex Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Flex
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster

To configure a forward proxy for Flex Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Flex Gateway does not have direct internet access, see
[Forward Proxy Flex Gateway Registration](#proxy-registration).

## Forward Proxy Flex Gateway Registration

If your Flex Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Flex Gateway deployment.

## See also

- [Register and Run Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

<!-- document id=d52b6934960ef6adb2acee55597470545daf488c5f179e6b917f5fdff0169b96 url=/mulesoft/current/en-us/gateway/1.9/flex-local-forward-proxy.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring a Forward Proxy for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Flex Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/1.9/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Flex Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/1.9/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Flex Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Flex
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Flex Gateway does not have direct internet access, see
    [Forward Proxy Flex Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Flex Gateway in a Kubernetes Cluster

To configure a forward proxy for Flex Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Flex Gateway does not have direct internet access, see
[Forward Proxy Flex Gateway Registration](#proxy-registration).

## Forward Proxy Flex Gateway Registration

If your Flex Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Flex Gateway deployment.

## See also

- [Register and Run Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

<!-- document id=40c5242eb3a2b231ef97595a857b409f6e32602f1a8a18ca63c457d0587d6dd3 url=/mulesoft/current/en-us/gateway/1.13/conn-forward-proxy.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring a Forward Proxy for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Omni Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/1.13/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Omni Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/1.13/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Omni Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Omni
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster

To configure a forward proxy for Omni Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Omni Gateway does not have direct internet access, see
[Forward Proxy Omni Gateway Registration](#proxy-registration).

## Forward Proxy Omni Gateway Registration

If your Omni Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/conn-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Omni Gateway deployment.

## See also

- [Register and Run Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

<!-- document id=670a7f1de3de856897943b24d2bc6799f107426af80d6c20df01458c5201a2fc url=/mulesoft/current/en-us/gateway/latest/conn-forward-proxy.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring a Forward Proxy for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Omni Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/latest/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Omni Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/latest/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Omni Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Omni
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster

To configure a forward proxy for Omni Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Omni Gateway does not have direct internet access, see
[Forward Proxy Omni Gateway Registration](#proxy-registration).

## Forward Proxy Omni Gateway Registration

If your Omni Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering an Omni Gateway](https://docs.mulesoft.com/gateway/latest/conn-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Omni Gateway deployment.

## See also

- [Register and Run Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

<!-- document id=67f62b662e37d4bfc1b92cd52862bcd5d055ea7a715bc055eb5b4d99640b73a8 url=/mulesoft/current/en-us/gateway/1.13/local-forward-proxy.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring a Forward Proxy for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Omni Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/1.13/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Omni Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/1.13/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Omni Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Omni
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster

To configure a forward proxy for Omni Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Omni Gateway does not have direct internet access, see
[Forward Proxy Omni Gateway Registration](#proxy-registration).

## Forward Proxy Omni Gateway Registration

If your Omni Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Omni Gateway deployment.

## See also

- [Register and Run Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

<!-- document id=c56dcc20b5d61241e19df9f450ea17f72c1617832c84f5e683a3a27506016c19 url=/mulesoft/current/en-us/gateway/latest/local-forward-proxy.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring a Forward Proxy for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

A forward proxy, such as Squid, enables you to route external HTTP Omni Gateway connections through
a proxy connection.

For both Connected Mode and Local Mode, you configure a forward proxy using YAML configuration
files.

The following diagram demonstrates how an internal network communicates with an external network
using a forward proxy.

![A flowchart that illustrates the journey of data from an app to a database to the cloud and back](/mulesoft/current/en-us/gateway/latest/_images/forward-proxy-diagram.png)

As in the diagram, when using a forward proxy, HTTP communication out of your internal network must
travel through the forward proxy.

In this example, all HTTP API upstream communication must also pass through the forward proxy. For
more information about how to enable some connections to communicate directly without the forward
proxy, see [noProxy Parameter](#noproxy-parameter).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure a Forward Proxy for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure a Forward Proxy for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Forward Proxy Connections

Only HTTP connections route through the forward proxy.

The following connections route through the forward proxy:

- Connections to Anypoint Platform

- Outbound policy connections

- Connections to upstream services

- HTTP (Fluent Bit) log connections

Using the `noProxy` parameter, you can configure HTTP and HTTPS connections to connect directly
without using the forward proxy.

Configuring a forward proxy does not alter these connections:

- Connections to shared storage

- Lightweight Directory Access Protocol (LDAP) connections

- Non-HTTP log connections

## noProxy Parameter

Adding the `noProxy` parameter enables HTTP services you trust to communicate without using the
forward proxy.

For example, when you enable `noProxy`, you can list HTTP log connections and connections to
upstream services to have them connect directly to Omni Gateway.

When using the `noProxy` parameter in the YAML configuration file to communicate with HTTP logs, you
must list the exact domain name. You cannot list the domain suffix, for example,
`.svc.cluster.local`. You need to list full domain name, `<logging-name>.svc.cluster.local`, for all
HTTP log connections.

The following diagram demonstrates the differences in communication using noProxy:

![Shows the difference between internal connections when <code>noProxy</code> is enabled or disabled](/mulesoft/current/en-us/gateway/latest/_images/no-proxy-diagram.png)

In the diagram, when you do not enable `noProxy`, Omni Gateway communicates with the internal API
endpoint using the forward proxy. When you enable `noProxy` and list the API Upstream domain, Omni
Gateway communicates directly with the internal API endpoint.

## Configuring Forward Proxy Parameters

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: forward-proxy
spec:
  forwardProxy:
    https:
      address: http://proxy:8888
      basicAuth:
        username: <string>
        password: <string>
    noProxy:
      - fluentd
      - .svc.cluster.local
```

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><p><code>https.address</code></p></td><td><p>required</p></td><td><p>Proxy adddress.</p></td></tr><tr><td><p><code>basicAuth</code></p></td><td><p>Optional</p></td><td><p>Supplies the authentication username and password.</p></td></tr><tr><td><p><code>basicAuth.username</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication username</p></td></tr><tr><td><p><code>basicAuth.Password</code></p></td><td><p>Required when <code>basicAuth</code> configured</p></td><td><p>Authentication password.</p></td></tr><tr><td><p><code>noProxy</code></p></td><td><p>Optional</p></td><td><p>Array containing domain names or IP addresses to communicate to without using the forward proxy. Each IP address must be listed in the array. The <code>noProxy</code> does not support CIDR blocks.</p></td></tr></tbody></table>

## Configure a Forward Proxy for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/forward-config.yaml
    ```

2.  Update the file with your desired forward proxy configuration details.

3.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired forward proxy configuration details.

4.  If your Omni Gateway does not have direct internet access, see
    [Forward Proxy Omni Gateway Registration](#proxy-registration).

## Configure a Forward Proxy for Omni Gateway in a Kubernetes Cluster

To configure a forward proxy for Omni Gateway, create a new YAML configuration resource with your
forward proxy details.

If your Omni Gateway does not have direct internet access, see
[Forward Proxy Omni Gateway Registration](#proxy-registration).

## Forward Proxy Omni Gateway Registration

If your Omni Gateway is in an internal network where all internet connections pass through the
forward proxy, you must add the `--https-proxy` flag when
[registering an Omni Gateway](https://docs.mulesoft.com/gateway/latest/local-reg-run).

Add the `--https-proxy` flag with your proxy `address` parameter:

\--https-proxy=http://proxy:8888

Provide your `username` and `password` parameters if you enable `basicAuth`:

\--https-proxy=http://<username>:<password>@proxy:8888

The following sample registration command shows flag placement:

```ssh
flexctl register \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
--https-proxy=http://<username>:<password>@proxy:8888 \
my-gateway
```

> [!NOTE] Use the relevant registration command for your Omni Gateway deployment.

## See also

- [Register and Run Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

<!-- document id=e5a34b4e55a41696a729022f46060cf2c3d6b8778a7549df519a35bcf0a4554b url=/mulesoft/current/en-us/gateway/1.12/flex-conn-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether a Flex Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Flex Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Flex Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Flex Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Flex Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Flex
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Flex Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Flex Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether a Flex Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Flex Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Flex Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Flex Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/reference/run/#healthcheck).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-health-check)

<!-- document id=ba15290c6a5a06d9cbd5d93dbc6931c74e5979380305dae21a010e3728290ae1 url=/mulesoft/current/en-us/gateway/1.12/flex-local-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether a Flex Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Flex Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Flex Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Flex Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Flex Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Flex
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Flex Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Flex Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether a Flex Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Flex Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Flex Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Flex Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/reference/run/#healthcheck).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-health-check)

<!-- document id=0c0874b853b6d01e4ecbd7216f9a18fd41ab8f03180b06ae39e19de00d65ad0d url=/mulesoft/current/en-us/gateway/1.13/conn-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether an Omni Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Omni Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Omni Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Omni Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Omni Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Omni
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Omni Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Omni Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether an Omni Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Omni Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Omni Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Omni Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/reference/run/#healthcheck).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-health-check)

<!-- document id=166a7282fb5c3a10f55bbe73919c3ea0007134d0a7f5ea1dda62280665134599 url=/mulesoft/current/en-us/gateway/1.13/local-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether an Omni Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Omni Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Omni Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Omni Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Omni Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Omni
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Omni Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Omni Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether an Omni Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Omni Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Omni Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Omni Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/reference/run/#healthcheck).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-health-check)

<!-- document id=a5ffeb8e9069ec5290b191021070c53044898ea3c89952b90c69e71a3e532763 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether a Flex Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Flex Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Flex Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Flex Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Flex Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Flex
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Flex Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Flex Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether a Flex Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Flex Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Flex Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Flex Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/containers/run/#healthchecks).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-health-check)

<!-- document id=472729c3b74f728c21fe31abde72dcf159edecb1c85bf2920e5ca88aafcc11a9 url=/mulesoft/current/en-us/gateway/1.9/flex-local-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether a Flex Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Flex Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Flex Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Flex Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Flex Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Flex
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Flex Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Flex Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether a Flex Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Flex Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Flex Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Flex Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Flex Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).

For Docker and Linux deployments, Flex Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/containers/run/#healthchecks).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-health-check)

<!-- document id=e88a8df34ae68b2247901ca1f0239fb6092828d18ee2987ba8426f36440f3009 url=/mulesoft/current/en-us/gateway/latest/conn-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether an Omni Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Omni Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Omni Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Omni Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Omni Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Omni
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Omni Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Omni Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether an Omni Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Omni Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Omni Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Omni Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/reference/run/#healthcheck).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/latest/policies-included-health-check)

<!-- document id=9e62e2e02cfb1dd45eeed08bd725a78b9b784e6bd0fdf4146e9a67f6476fae64 url=/mulesoft/current/en-us/gateway/latest/local-readiness-liveness.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring a Readiness or Liveness Probe

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports two methods for ensuring reliability and efficiency.

- Readiness probes test whether a gateway instance is configured correctly and ready for incoming
  traffic. This ensures that end-users are not affected by partially configured APIs. For
  information, refer to [Configure a Readiness Probe](#configure-a-readiness-probe).

- Liveness probes test whether a gateway instance is operational. This minimizes downtime due to
  crashes or other failures. For information, refer to
  [Configure a Liveness Probe](#configure-a-liveness-probe).

## Configure a Readiness Probe

To test whether an Omni Gateway instance is ready for incoming traffic, use the following CLI
command:

```ssh
flexctl probe --check=readiness
```

If the Omni Gateway instance is ready to receive incoming traffic, the command returns an exit code
of `0`. Otherwise, the command returns an exit code of `1`.

When Omni Gateway starts, its readiness state is `false`. The state changes to `true` after the
following conditions are met:

- API instances are deployed (at least one API must be configured)

- Policies are initialized

The readiness state is not impacted when you apply configuration changes to a running gateway
instance. This ensures that the instance continues to receive traffic during configuration updates.

Refer to the following for information about configuring readiness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a readiness probe configured in the Helm
chart. The readiness probe automatically runs
`flexctl probe --check=readiness --allow-api-errors --allow-envoy-errors --allow-policy-errors` at
an interval of 10 seconds.

The readiness probe has the following default values:

```helm
readinessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=readiness
   - --allow-api-errors
   - --allow-envoy-errors
   - --allow-policy-errors
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 2
 timeoutSeconds: 5
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The readiness probe command</p></td></tr><tr><td><p><code>--allow-api-errors</code></p></td><td><p>The flag to allow errors in API instances</p></td></tr><tr><td><p><code>--allow-envoy-errors</code></p></td><td><p>The flag to allow Envoy configuration errors</p></td></tr><tr><td><p><code>--allow-policy-errors</code></p></td><td><p>The flag to allow policy configuration errors</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before executing the first readiness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each readiness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed readiness probes before the Kubernetes readiness status is set to <code>false</code></p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the readiness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).

The default Kubernetes readiness probe is configured to be error-tolerant. This enables Omni Gateway
to scale even though there might be configuration errors. To learn more about error tolerance, see
[Configure Error Tolerance](#configure-error-tolerance).

> [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
> there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This isn’t
> an issue with custom readiness probe configurations.

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default readiness
probe. However, you can run the readiness probe command manually or configure it for automated use
with external third-party services. Besides the Kubernetes readiness probe, MuleSoft doesn’t provide
support for third-party readiness probes.

### Configure External Components

Configure your external components to query the readiness state. For example, in AWS virtual
machines that run behind a load balancer, configure the readiness query as a health check. To expose
the readiness API to external components, apply the following configuration to the Omni Gateway
instance:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: probe
spec:
  probe:
    enabled: true
    port: 3000
```

Applying the YAML configuration snippet enables the readiness API to respond to `GET` requests:

`http://<flex-gateway-url>:<port-configured>/probes/readiness?allowEnvoyErrors=<true|false>&allowAPIErrors=<true|false>&allowPolicyErrors=<true|false>`

### Configure Error Tolerance

You can configure the readiness probe error intolerant or error tolerant. For error-intolerant,
misconfigured gateway instances never reach a readiness state of `true`. For error-tolerant
deployments, if a configuration error occurs (for example, if you misconfigure a policy), the
readiness state is still `true` after the API instances and policies are deployed. This enables Omni
Gateway to scale even though there might be configuration errors.

The readiness CLI command provides the following flags to configure error tolerance:

- `--allow-api-errors`

- `--allow-envoy-errors`

- `--allow-policy-errors`

In deployments that query the readiness state through HTTP requests to the readiness API, use these
query parameters:

- `allowEnvoyErrors=false`

- `allowAPIErrors=false`

- `allowPolicyErrors=false`

### Probe Readiness During Shutdown

Readiness is also probed during shutdown, when the gateway sends a `Connection: close` header. A
`SIGTERM` signal initiates a drain of downstream connections by signaling them to reconnect. The
default drain period is 25 seconds, after which Omni Gateway exits gracefully.

You can modify a drain period via the `FLEX_SERVICE_ENVOY_DRAIN_TIME` environment variable in Docker
and Linux, or the `gateway.drainSeconds` option in a Kubernetes Helm chart.

Omni Gateway is preconfigured for a graceful shutdown of 30 seconds, which is 5 seconds more than
the drain period. When increasing the drain period, also increase the shutdown period using
`TimeoutStopSec` in Linux or `terminationGracePeriodSeconds` in Kubernetes. The shutdown period must
exceed the drain period.

The default readiness probe in Kubernetes runs every 10 seconds with a failure threshold of 2,
allowing shutdown detection within 20 seconds. This ensures that no new traffic is sent to the
instance shutting down. Use similar configurations with readiness probes in other environments like
AWS Load Balancer.

## Configure a Liveness Probe

To test whether an Omni Gateway instance is operational, use the following CLI command:

```ssh
flexctl probe --check=liveness
```

If the Omni Gateway instance is operational, the command returns an exit code of `0`. Otherwise, the
command returns an exit code of `1`.

You can either run the liveness probe command manually, or configure the command to run
automatically. By default, Omni Gateway Kubernetes deployments have an automatic liveness probe
configured. The default probe periodically runs the liveness probe command and automatically
restarts the Omni Gateway pod after a specified number of failures.

Refer to the following for information about configuring liveness probes in specific environments:

- Kubernetes and OpenShift

- Docker, Podman, and Linux

By default, Omni Gateway running on Kubernetes includes a liveness probe configured in the Helm
chart. The liveness probe automatically runs `flexctl probe --check=liveness` at an interval of 10
seconds and restarts non-operational pods after 5 failed tests.

The liveness probe is configured by default with the following values:

```helm
livenessProbe:
 exec:
   command:
   - flexctl
   - probe
   - --check=liveness
 initialDelaySeconds: 10
 periodSeconds: 10
 failureThreshold: 5
 timeoutSeconds: 1
```

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Parameter</p></td><td><p>Description</p></td></tr><tr><td><p><code>exec.command</code></p></td><td><p>The liveness probe command</p></td></tr><tr><td><p><code>initialDelaySeconds</code></p></td><td><p>The time in seconds to wait after startup before running the first liveness probe</p></td></tr><tr><td><p><code>periodSeconds</code></p></td><td><p>The period in seconds between each liveness probe</p></td></tr><tr><td><p><code>failureThreshold</code></p></td><td><p>The number of failed liveness probes before the Kubernetes pod is restarted</p></td></tr><tr><td><p><code>timeoutSeconds</code></p></td><td><p>The time in seconds before the liveness probe times out</p></td></tr></tbody></table>

To modify the default parameters, update your Helm chart. You can modify these parameters during or
after the initial installation of the Helm chart. For more information about updating a Helm chart,
see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).

For Docker and Linux deployments, Omni Gateway doesn’t include a pre-configured default liveness
probe. However, you can run the liveness probe command manually, or configure it for automated use
with third-party services. Besides the Kubernetes liveness probe, MuleSoft doesn’t provide support
for third-party liveness probes.

One method of running the liveness probe command with Docker is to configure `HEALTHCHECK` in your
`docker run` command. For more information, see
[Docker run HEALTHCHECK](https://docs.docker.com/engine/reference/run/#healthcheck).

## See Also

- [Configure Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

- [Health Check Policy](https://docs.mulesoft.com/gateway/latest/policies-included-health-check)

<!-- document id=a48ca6885b68ed31e421adbf79a3a4df8d0e4195be31be45a1bf9e7bb156af9e url=/mulesoft/current/en-us/gateway/1.13/conn-distributed-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Distributed Shared Storage for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Enable distributed shared storage for distributed caching, gateway configuration caching (Connected
Mode), and rate limiting policies.

Distributed shared storage enables multiple gateway replicas to share state across a distributed
deployment.

Distributed shared storage isn’t persistent and data is lost when all replicas go down (scaled to
zero replicas). For persistent shared storage,
[configure Redis shared storage](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config).

You configure distributed shared storage via a storage YAML file.

The following steps demonstrate distributed shared storage support for Omni Gateway running in a
Docker container, as a Linux service, or as a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your distributed shared storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding distributed shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: api-shared-storage
spec:
  sharedStorage:
    objectStore:
      url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## See Also

- [Configuring Distributed Shared Storage for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-distributed-shared-storage-config)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#shared-storage)

<!-- document id=dc19e19af74cdc0db329e6c3c813442cab1adf59d36e295024d98647b1fb18d9 url=/mulesoft/current/en-us/gateway/latest/conn-distributed-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Distributed Shared Storage for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Enable distributed shared storage for distributed caching, gateway configuration caching (Connected
Mode), and rate limiting policies.

Distributed shared storage enables multiple gateway replicas to share state across a distributed
deployment.

Distributed shared storage is persistent, but data is lost when all replicas go down (scaled to zero
replicas). For persistent shared storage,
[configure Redis shared storage](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config).

You configure distributed shared storage via a storage YAML file.

The following steps demonstrate distributed shared storage support for Omni Gateway running in a
Docker container, as a Linux service, or as a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your distributed shared storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding distributed shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: api-shared-storage
spec:
  sharedStorage:
    objectStore:
      url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## See Also

- [Configuring Distributed Shared Storage for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-distributed-shared-storage-config)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#shared-storage)

<!-- document id=2a734c829383e566a44e4382fbc338133a7e59063eaedea056497d3243312a36 url=/mulesoft/current/en-us/gateway/1.13/local-distributed-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Distributed Shared Storage for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Enable distributed shared storage for distributed caching, gateway configuration caching (Connected
Mode), and rate limiting policies.

Distributed shared storage enables multiple gateway replicas to share state across a distributed
deployment.

Distributed shared storage isn’t persistent and data is lost when all replicas go down (scaled to
zero replicas). For persistent shared storage,
[configure Redis shared storage](https://docs.mulesoft.com/gateway/1.13/local-shared-storage-config).

You configure distributed shared storage via a storage YAML file.

The following steps demonstrate distributed shared storage support for Omni Gateway running in a
Docker container, as a Linux service, or as a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your distributed shared storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding distributed shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: api-shared-storage
spec:
  sharedStorage:
    objectStore:
      url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## See Also

- [Configuring Distributed Shared Storage for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-distributed-shared-storage-config)

- [Declarative Configuration Reference](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#shared-storage)

<!-- document id=54f7faed16ebba89c81367f1967d7af55adba34f47b9c462dc76e03e9f807a2f url=/mulesoft/current/en-us/gateway/latest/local-distributed-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Distributed Shared Storage for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Enable distributed shared storage for distributed caching, gateway configuration caching (Connected
Mode), and rate limiting policies.

Distributed shared storage enables multiple gateway replicas to share state across a distributed
deployment.

Distributed shared storage is persistent, but data is lost when all replicas go down (scaled to zero
replicas). For persistent shared storage,
[configure Redis shared storage](https://docs.mulesoft.com/gateway/latest/local-shared-storage-config).

You configure distributed shared storage via a storage YAML file.

The following steps demonstrate distributed shared storage support for Omni Gateway running in a
Docker container, as a Linux service, or as a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/local-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your distributed shared storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding distributed shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: api-shared-storage
    spec:
      sharedStorage:
        objectStore:
          url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
    ```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding distributed shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: api-shared-storage
spec:
  sharedStorage:
    objectStore:
      url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

## See Also

- [Configuring Distributed Shared Storage for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-distributed-shared-storage-config)

- [Declarative Configuration Reference](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#shared-storage)

<!-- document id=1d8b78f620d3c0d9d10cc497a98ce1c2ceb25d53f4c1c373879e0640bb464281 url=/mulesoft/current/en-us/gateway/1.12/flex-managed-tracing-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Distributed Tracing for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Flex Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Flex Gateway APIs and external
services.

Tracing enables you to track Flex Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Flex Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

## Before You Begin

To use the OpenTelemetry with Flex Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Enable and Configure Distributed Tracing for your Managed Flex Gateway

To enable distributed tracing for your Managed Flex Gateway:

1.  From Anypoint Platform, select **Runtime Manager > Flex Gateways**.

2.  Click the Managed Flex Gateway name.

3.  In the navigation menu, click Settings.

4.  Click **Advanced options**.

5.  Click **Tracing**.

6.  Turn on **Distributed tracing**.

7.  Set the **Sampling percentage** to the percentage of transactions that you want to trace.

    - This setting corresponds to the `overall` sampling percentage. The `client` and `random`
      sampling percentages are set to 100% by default, if the sampling percentage is set to a
      non-zero value here.

    - Set the **Sampling percentage** to 0 if you want to specify the sampling percentage only on a
      per-API basis, using the Tracing policy.

8.  Click **Apply Changes**.

## Export traces from the Anypoint Monitoring Telemetry Exporter

To export traces to third party providers using the Anypoint Monitoring Telemetry Exporter, see
[How to export telemetry data to third-party monitoring systems](https://docs.mulesoft.com/monitoring/telemetry-exporter).

## Configure Distributed Tracing For Specific APIs

You can override the globally configured distributed tracing settings by applying the Tracing Policy
to specific APIs. You must first enable and configure distributed tracing for the gateway. You can
then apply this policy to the APIs you want to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-tracing)

<!-- document id=0b79f59ee6d4a4c068fb26fc0a689b93f5eee1feb4ee6ffdbe448efab6aa79f3 url=/mulesoft/current/en-us/gateway/1.13/managed-tracing-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Distributed Tracing for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Omni Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Omni Gateway APIs and external
services.

Tracing enables you to track Omni Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Omni Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

Configure distributed tracing for Managed Omni Gateway using one of these methods:

- [Managed Omni Gateway deployment](#managed-deployment-config): Set initial distributed tracing
  values when you create the gateway.

- [Runtime Manager runtime configurations](#runtime-manager-config): Applies to all API instances in
  the gateway after the gateway is deployed.

- [Policy](#policy-config): Applies to one API instance and provides granular control.

## Before You Begin

To use the OpenTelemetry with Omni Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Configure Distributed Tracing During Managed Gateway Deployment

Set distributed tracing values in the deployment flow when you create a Managed Omni Gateway. For
the UI steps and parameter descriptions, see
[Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-managed-set-up).

## Configuring Omni Gateway Distributed Tracing in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Distributed Tracing**.

6.  Enable **Distributed tracing**.

7.  Set the **Sampling percentage** to the percentage of transactions to trace.

    To configure sampling only on a per-API basis with the Tracing policy, set **Sampling
    percentage** to `0`.

8.  Apply the changes.

> [!NOTE] The **Sampling percentage** corresponds to the `overall` sampling percentage. The `client`
> and `random` sampling percentages default to `100` when **Sampling percentage** is set to a
> non-zero value.

## Configure Distributed Tracing for Specific APIs

To override the globally configured distributed tracing settings for specific APIs, apply the
Tracing policy. First enable and configure distributed tracing for the gateway, then apply this
policy to the APIs to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-tracing)

## Export Traces from Anypoint Monitoring to Third Parties

To export traces to third-party providers using the Anypoint Monitoring Telemetry Exporter, see
[Exporting Telemetry Data to Third-Party Monitoring Systems](https://docs.mulesoft.com/monitoring/telemetry-exporter).

<!-- document id=4c83bbcdb71f9ca67287bb736b2b98c88fa4f02524d7934ff2c5ef78598abf0f url=/mulesoft/current/en-us/gateway/latest/managed-tracing-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Distributed Tracing for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Omni Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Omni Gateway APIs and external
services.

Tracing enables you to track Omni Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Omni Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

Configure distributed tracing for Managed Omni Gateway using one of these methods:

- [Managed Omni Gateway deployment](#managed-deployment-config): Set initial distributed tracing
  values when you create the gateway.

- [Runtime Manager runtime configurations](#runtime-manager-config): Applies to all API instances in
  the gateway after the gateway is deployed.

- [Policy](#policy-config): Applies to one API instance and provides granular control.

## Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set,
in this order of precedence:

1.  **Policy**: A policy applied to the API instance.

2.  **Runtime Manager runtime configuration**: Used if no policy value is set.

3.  **Built-in default**: Used if neither of the other values is set. A policy value overrides the
    gateway-level value for the API instance it’s applied to. API instances without the policy use
    the gateway-level value.

## Before You Begin

To use the OpenTelemetry with Omni Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Configure Distributed Tracing During Managed Gateway Deployment

Set distributed tracing values in the deployment flow when you create a Managed Omni Gateway. For
the UI steps and parameter descriptions, see
[Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up).

## Configuring Omni Gateway Distributed Tracing in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Distributed Tracing**.

6.  Enable **Distributed tracing**.

7.  Set the **Sampling percentage** to the percentage of transactions to trace.

    To configure sampling only on a per-API basis with the Tracing policy, set **Sampling
    percentage** to `0`.

8.  Apply the changes.

> [!NOTE] The **Sampling percentage** corresponds to the `overall` sampling percentage. The `client`
> and `random` sampling percentages default to `100` when **Sampling percentage** is set to a
> non-zero value.

## Configure Distributed Tracing for Specific APIs

To override the globally configured distributed tracing settings for specific APIs, apply the
Tracing policy. First enable and configure distributed tracing for the gateway, then apply this
policy to the APIs to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/latest/policies-included-tracing)

## Export Traces from Anypoint Monitoring to Third Parties

To export traces to third-party providers using the Anypoint Monitoring Telemetry Exporter, see
[Exporting Telemetry Data to Third-Party Monitoring Systems](https://docs.mulesoft.com/monitoring/telemetry-exporter).

<!-- document id=a1cf1c05eeaa57de31624b2d93f4e10cbdc09b55a6756ee76626df95f3ae0a28 url=/mulesoft/current/en-us/gateway/1.12/flex-local-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring External Logs for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway enables you to deliver runtime and access logs to any supported Fluent Bit
v3.2.10 output type. You configure log output via a custom YAML file. Additionally, to view access
logs, you must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Flex Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.2.10 output type, such
as `Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Flex Gateway maintains
standard output logs. Use the standard output logs for quick checks when additional log output is
not needed. To view the standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs). Both
runtime and access logs appear in standard output logs. However, access logs are only present if you
apply a Message Logging policy.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Flex Gateway log output, complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://www.dynatrace.com/support/help/get-started/monitoring-environment/environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://www.dynatrace.com/support/help/manage/access-control/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Flex Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Flex Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Flex Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Flex Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.12/flex-local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.12/flex-local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Kubernetes Cluster

To configure logging for Flex Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.12/flex-local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Flex Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

Configuring a Message Logging policy makes access logs visible in both standard output logs and your
third-party log services.

To apply a Message Logging policy, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-secure-local)
and use the [Message Logging Configuration Parameters](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging).

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Message Logging Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-message-logging)

<!-- document id=998fec18f6468006874e7f11c3c720abbd672af25b0bf373f285c102b9ee5186 url=/mulesoft/current/en-us/gateway/1.9/flex-local-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring External Logs for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway enables you to deliver runtime and access logs to any supported Fluent Bit
v3.0 output type. You configure log output via a custom YAML file. Additionally, to view access
logs, you must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Flex Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.0 output type, such as
`Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Flex Gateway maintains
standard output logs. Use the standard output logs for quick checks when additional log output is
not needed. To view the standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs). Both
runtime and access logs appear in standard output logs. However, access logs are only present if you
apply a Message Logging policy.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Flex Gateway log output, complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://docs.dynatrace.com/docs/discover-dynatrace/get-started/monitoring-environment#environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Flex Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Flex Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.0 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Flex Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Flex Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.9/flex-local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.9/flex-local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Kubernetes Cluster

To configure logging for Flex Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.9/flex-local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Flex Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

Configuring a Message Logging policy makes access logs visible in both standard output logs and your
third-party log services.

To apply a Message Logging policy, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-secure-local)
and use the [Message Logging Configuration Parameters](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging).

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/1.9/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Message Logging Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-message-logging)

<!-- document id=49cd1a97d3dc039e6164f91170fdc0f5cee19370b92f617b82527c49a97fb5f7 url=/mulesoft/current/en-us/gateway/1.13/local-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring External Logs for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables you to deliver runtime and access logs to any supported Fluent Bit v3.2.10
output type. You configure log output via a custom YAML file. Additionally, to view access logs, you
must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Omni Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.2.10 output type, such
as `Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Omni Gateway maintains
standard output logs. Use the standard output logs for quick checks when additional log output is
not needed. To view the standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs). Both
runtime and access logs appear in standard output logs. However, access logs are only present if you
apply a Message Logging policy.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Omni Gateway log output, complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://www.dynatrace.com/support/help/get-started/monitoring-environment/environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://www.dynatrace.com/support/help/manage/access-control/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Omni Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Omni Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Omni Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Omni Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.13/local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.13/local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Kubernetes Cluster

To configure logging for Omni Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/1.13/local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Omni Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

Configuring a Message Logging policy makes access logs visible in both standard output logs and your
third-party log services.

To apply a Message Logging policy, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-secure-local) and
use the [Message Logging Configuration Parameters](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging).

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Message Logging Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-message-logging)

<!-- document id=8dc4eb05c76d3d849a68365b7965b5ec6a389a9abca2377e3b62573656bf36e5 url=/mulesoft/current/en-us/gateway/latest/local-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring External Logs for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables you to deliver runtime and access logs to any supported Fluent Bit v3.2.10
output type. You configure log output via a custom YAML file. Additionally, to view access logs, you
must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Omni Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.2.10 output type, such
as `Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Omni Gateway maintains
standard output logs. Use the standard output logs for quick checks when additional log output is
not needed. To view the standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs). Both runtime and
access logs appear in standard output logs. However, access logs are only present if you apply a
Message Logging policy.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Omni Gateway log output, complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/local-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://www.dynatrace.com/support/help/get-started/monitoring-environment/environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://www.dynatrace.com/support/help/manage/access-control/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Omni Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Omni Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Omni Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Omni Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Kubernetes Cluster

To configure logging for Omni Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway standard output logs for any
      configuration errors.

      To view standard output logs, see [View Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Omni Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

Configuring a Message Logging policy makes access logs visible in both standard output logs and your
third-party log services.

To apply a Message Logging policy, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-local) and
use the [Message Logging Configuration Parameters](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging).

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Message Logging Policy](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging)

<!-- document id=5eefd33c210a714835f335b446222df9712546eb1e8441c32ae8668b76dfb363 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-configure.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway enables configuration via Anypoint Platform or declarative configuration files. You can
configure Flex gateway running in Connected Mode via both Anypoint Platform or declarative
configuration files, while you can configure Managed Flex Gateway only with Anypoint Platform and
Flex Gateway running in local mode only with configuration files.

Configurations include:

- Replicas

- TLS contexts

- Shared storage

- Forward proxies

- Automated Jenkins pipelines

- Node selection for Kubernetes deployments

For Connected Mode, see [Configuring Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-configure).

For Local Mode, see [Configuring Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-configure).

## See Also

- [Configuring Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-configure)

- [Configuring Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-configure)

- [Configuring Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-configure)

<!-- document id=2624d70979ed0c04fb375c8d85d479195fab262e26b0cc995a04119c9897256b url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-configure.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway enables configuration via Anypoint Platform or declarative configuration files. You can
configure Flex gateway running in Connected Mode via both Anypoint Platform or declarative
configuration files, while you can configure Managed Flex Gateway only with Anypoint Platform and
Flex Gateway running in local mode only with configuration files.

Configurations include:

- Replicas

- TLS contexts

- Shared storage

- Forward proxies

- Automated Jenkins pipelines

- Node selection for Kubernetes deployments

For Connected Mode, see [Configuring Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-configure).

For Local Mode, see [Configuring Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-configure).

## See Also

- [Configuring Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-configure)

- [Configuring Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-configure)

- [Configuring Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-configure)

<!-- document id=5d7ab7a0c58a0b6b5ed107903019e0806e8c73e3c34be495b7db109c2f669d6f url=/mulesoft/current/en-us/gateway/1.12/flex-conn-replica-caching.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway Configuration Caching in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To reduce scale-up time and increases resiliency, Flex Gateway can cache its gateway configuration
in Redis shared storage. Flex replicas use the cached gateway configuration instead of each replica
directly downloading the configuration from Anypoint Platform. By default, configuration caching is
not enabled.

Flex Gateway configuration caching works by:

1.  After the first Flex replica starts, the replica downloads the configuration from Anypoint
    Platform, encrypts the configuration, and stores it in Redis.

2.  After subsequent replicas start, they use the locally cached configuration rather than
    downloading from Anypoint Platform.

3.  If the Flex Gateway configuration changes on Anypoint Platform, the replicas download the
    necessary configuration from Anypoint Platform and store it in Redis for immediate use by the
    other replicas.

If caching is configured and Redis errors occur, each replica downloads configurations directly from
Anypoint Platform. If Flex Gateway disconnects from Anypoint Platform, Flex gateway uses the cached
configuration until connections are restored.

## Enable Flex Gateway Configuration Caching

1.  Ensure the Redis shared storage is configured.

    To learn more, see
    [Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config).

2.  Enable the `FLEX_DATASOURCE_CONTROL_NODE_ENABLED=true` environment variable.

<!-- document id=a39249a0f87716c55da258779f6b5a2099c3c50e82d17ab80be2d7c39f4c9f8c url=/mulesoft/current/en-us/gateway/1.9/flex-conn-replica-caching.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Flex Gateway Configuration Caching in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To reduce scale-up time and increases resiliency, Flex Gateway can cache its gateway configuration
in Redis shared storage. Flex replicas use the cached gateway configuration instead of each replica
directly downloading the configuration from Anypoint Platform. By default, configuration caching is
not enabled.

Flex Gateway configuration caching works by:

1.  After the first Flex replica starts, the replica downloads the configuration from Anypoint
    Platform, encrypts the configuration, and stores it in Redis.

2.  After subsequent replicas start, they use the locally cached configuration rather than
    downloading from Anypoint Platform.

3.  If the Flex Gateway configuration changes on Anypoint Platform, the replicas download the
    necessary configuration from Anypoint Platform and store it in Redis for immediate use by the
    other replicas.

If caching is configured and Redis errors occur, each replica downloads configurations directly from
Anypoint Platform. If Flex Gateway disconnects from Anypoint Platform, Flex gateway uses the cached
configuration until connections are restored.

## Enable Flex Gateway Configuration Caching

1.  Ensure the Redis shared storage is configured.

    To learn more, see
    [Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config).

2.  Enable the `FLEX_DATASOURCE_CONTROL_NODE_ENABLED=true` environment variable.

<!-- document id=51f6f35342d2b19e7b8f88d31ba7c1fc1427a58a3353d28419daa824fd853b71 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-tracing-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway Distributed Tracing in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Flex Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Flex Gateway APIs and external
services.

Tracing enables you to track Flex Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Flex Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

## Before You Begin

To use the OpenTelemetry with Flex Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Export traces from the Anypoint Monitoring Telemetry Exporter

To export traces to third party providers using the Anypoint Monitoring Telemetry Exporter, see
[How to export telemetry data to third-party monitoring systems](https://docs.mulesoft.com/monitoring/telemetry-exporter).

To export traces using the Anypoint Monitoring Telemetry Exporter, first configure the Telemetry
Exporter in Anypoint Monitoring.

## Export Traces to Anypoint Monitoring

Edit and then apply this configuration resource to enable distributed tracing. This configuration
resource applies to all API instances. This example sets sampling to 0% for all traces, and sampling
is configured on a per-API basis using policies.

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: anypoint
      properties:
        timeout: 10s
    sampling:
      client: 0
      random: 0
      overall: 0
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Export Traces to a gRPC OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a gRPC endpoint in Flex, use the following YAML
configuration as an example:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: h2://splunk-otel-collector-agent.default.svc.cluster.local:4317
        serviceType: grpc
        serviceName: my-flex-name
        timeout: 10s
        resourceAttributes:
          any-key: any-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Export Traces to a HTTP OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a HTTP endpoint, use the following YAML configuration as an
example:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: http://opentelemetry:4318
        tracesUri: http://opentelemetry:4318/v1/traces
        serviceType: http
        serviceName: the-name
        timeout: 10s
        httpHeaders:
          auth: samething
        resourceAttributes:
          nay-key: nay-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Configure Distributed Tracing For Specific APIs

You can override the globally configured distributed tracing settings by applying the Tracing Policy
to specific APIs. You must first enable and configure distributed tracing for the gateway. You can
then apply this policy to the APIs you want to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-tracing)

<!-- document id=f240e96437bc39fb4ffc63126e5e752f082c237f6d998f1aa80a5560f11c7e37 url=/mulesoft/current/en-us/gateway/1.12/flex-local-tracing-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway Distributed Tracing in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Flex Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Flex Gateway APIs and external
services.

Tracing enables you to track Flex Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Flex Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

## Before You Begin

To use the OpenTelemetry with Flex Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Export Traces to a gRPC OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a gRPC endpoint in Flex, use the following YAML
configuration as an example:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: h2://splunk-otel-collector-agent.default.svc.cluster.local:4317
        serviceType: grpc
        serviceName: my-flex-name
        timeout: 10s
        resourceAttributes:
          any-key: any-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Export Traces to a HTTP OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a HTTP endpoint, use the following YAML configuration as an
example:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: http://opentelemetry:4318
        tracesUri: http://opentelemetry:4318/v1/traces
        serviceType: http
        serviceName: the-name
        timeout: 10s
        httpHeaders:
          auth: samething
        resourceAttributes:
          nay-key: nay-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Configure Distributed Tracing For Specific APIs

You can override the globally configured distributed tracing settings by applying the Tracing Policy
to specific APIs. You must first enable and configure distributed tracing for the gateway. You can
then apply this policy to the APIs you want to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-tracing)

<!-- document id=165f028ef84bb4fc7a5658e2130ead7efb2819865ef223818b26ab9dd7d3a21e url=/mulesoft/current/en-us/gateway/1.12/flex-conn-configure.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/1.12/flex-conn-rep-run) - Anypoint Flex Gateway enables you to create replicas,
  which are instances of Flex Gateway. By default, Flex Gateway runs as a single replica. Running
  multiple replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config) - Flex Gateway enables you to configure a TLS
  context to support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config) - Flex Gateway enables you to
  configure shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/1.12/flex-conn-forward-proxy) - Flex Gateway enables you to configure a
  forward proxy to route external HTTP connections through a proxy connection.

- [Configure with the API Manager API Tool](https://docs.mulesoft.com/gateway/1.12/flex-conn-manage-public-api) - Flex Gateway enables you
  to configure and manage Flex Gateway via the API Manager API tool, a command-line tool used to
  communicate with API Manager.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/1.12/flex-conn-readiness-liveness) - Flex Gateway enables you to run a
  liveness check command to test gateway health. Additionally, Flex Gateways deployed on Kubernetes
  include a liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/1.12/flex-conn-proxy-protocol) - Flex Gateway supports PROXY protocol to
  perserve client IP address when servicing multi-layer connections.

- [Automate Flex Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/1.12/flex-conn-jenkins-cli) - Flex
  Gateway enables you to build a Jenkins Pipeline by using Anypoint CLI to automate workflows.

- [Automate Flex Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.12/flex-conn-jenkins-api) -
  Flex Gateway enables you to build a Jenkins Pipeline by using the API Manager API to automate
  workflows.

- [Configure Distributed Tracing](https://docs.mulesoft.com/gateway/1.12/flex-conn-tracing-config) - Flex Gateway enables you to configure
  distributed tracing for your APIs.

<!-- document id=06b48d1e5d9a35c1941e1a962a5be2e04807c3e3344dcd5601055fbf3e53b2cf url=/mulesoft/current/en-us/gateway/1.9/flex-conn-configure.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/1.9/flex-conn-rep-run) - Anypoint Flex Gateway enables you to create replicas,
  which are instances of Flex Gateway. By default, Flex Gateway runs as a single replica. Running
  multiple replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config) - Flex Gateway enables you to configure a TLS
  context to support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config) - Flex Gateway enables you to
  configure shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/1.9/flex-conn-forward-proxy) - Flex Gateway enables you to configure a
  forward proxy to route external HTTP connections through a proxy connection.

- [Configure with the API Manager API Tool](https://docs.mulesoft.com/gateway/1.9/flex-conn-manage-public-api) - Flex Gateway enables you
  to configure and manage Flex Gateway via the API Manager API tool, a command-line tool used to
  communicate with API Manager.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/1.9/flex-conn-readiness-liveness) - Flex Gateway enables you to run a
  liveness check command to test gateway health. Additionally, Flex Gateways deployed on Kubernetes
  include a liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/1.9/flex-conn-proxy-protocol) - Flex Gateway supports PROXY protocol to
  perserve client IP address when servicing multi-layer connections.

- [Automate Flex Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/1.9/flex-conn-jenkins-cli) - Flex
  Gateway enables you to build a Jenkins Pipeline by using Anypoint CLI to automate workflows.

- [Automate Flex Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.9/flex-conn-jenkins-api) -
  Flex Gateway enables you to build a Jenkins Pipeline by using the API Manager API to automate
  workflows.

<!-- document id=d40a54bda61658a77b78abc224d6647f5e0594371ce48ab4c4b221d91599eb84 url=/mulesoft/current/en-us/gateway/1.12/flex-local-configure.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/1.12/flex-local-rep-run) - Anypoint Flex Gateway enables you to create replicas,
  which are instances of Flex Gateway. By default, Flex Gateway runs as a single replica. Running
  multiple replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config) - Flex Gateway enables you to configure a TLS
  context to support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/1.12/flex-local-shared-storage-config) - Flex Gateway enables you to
  configure shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/1.12/flex-local-forward-proxy) - Flex Gateway enables you to configure a
  forward proxy to route external HTTP connections through a proxy connection.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/1.12/flex-local-readiness-liveness) - Flex Gateway enables you to run a
  liveness check command to test gateway health. Additionally, Flex Gateways deployed on Kubernetes
  include a liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/1.12/flex-local-proxy-protocol) - Flex Gateway supports PROXY protocol to
  perserve client IP address when servicing multi-layer connections.

- [Configure Distributed Tracing](https://docs.mulesoft.com/gateway/1.12/flex-local-tracing-config) - Flex Gateway enables you to configure
  distributed tracing for your APIs.

Refer to the [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide)
for information about configuring Flex Gateway via declarative configuration files.

<!-- document id=8df9177f21400a1e40906610507e088e8fc129cb298b14c840bf82ee68b39707 url=/mulesoft/current/en-us/gateway/1.9/flex-local-configure.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/1.9/flex-local-rep-run) - Anypoint Flex Gateway enables you to create replicas,
  which are instances of Flex Gateway. By default, Flex Gateway runs as a single replica. Running
  multiple replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config) - Flex Gateway enables you to configure a TLS
  context to support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/1.9/flex-local-shared-storage-config) - Flex Gateway enables you to
  configure shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/1.9/flex-local-forward-proxy) - Flex Gateway enables you to configure a
  forward proxy to route external HTTP connections through a proxy connection.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/1.9/flex-local-readiness-liveness) - Flex Gateway enables you to run a
  liveness check command to test gateway health. Additionally, Flex Gateways deployed on Kubernetes
  include a liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/1.9/flex-local-proxy-protocol) - Flex Gateway supports PROXY protocol to
  perserve client IP address when servicing multi-layer connections.

Refer to the [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide)
for information about configuring Flex Gateway via declarative configuration files.

<!-- document id=56823938a414719fed8bcf7ba7ba71d6eb20594062b6ecc177cfcb7b96a50a8e url=/mulesoft/current/en-us/gateway/1.12/flex-conn-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway Log Output for Third-Party Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway enables you to deliver runtime and access logs to any supported Fluent Bit
v3.2.10 output type. You configure log output via a custom YAML file. Additionally, to view access
logs, you must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Flex Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.2.10 output type, such
as `Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Flex Gateway sends
runtime logs to runtime manager and access logs to API Manager. To learn more, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-runtime-manager)

- [Configuring Message Logging for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-message-log).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Flex Gateway log output, complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://www.dynatrace.com/support/help/get-started/monitoring-environment/environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://www.dynatrace.com/support/help/manage/access-control/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Flex Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Flex Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Flex Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Flex Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Kubernetes Cluster

To configure logging for Flex Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Flex Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

To configure a Message Logging policy, see
[Configuring Message Logging for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-message-log).

Configuring a Message Logging policy makes access logs visible in both API Manager **Logs** and your
third-party log services.

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide#logging)

- [Configuring Message Logging for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-message-log)

- [Disabling Flex Gateway Log Output to Anypoint Platform](https://docs.mulesoft.com/gateway/1.12/flex-conn-disable-logs)

<!-- document id=8aaec20eceeb17f57aa7b7ef8476dd43efde7cb0b953be7a71ce106418b5f137 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Flex Gateway Log Output for Third-Party Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway enables you to deliver runtime and access logs to any supported Fluent Bit
v3.0 output type. You configure log output via a custom YAML file. Additionally, to view access
logs, you must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Flex Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.0 output type, such as
`Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Flex Gateway sends
runtime logs to runtime manager and access logs to API Manager. To learn more, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-runtime-manager)

- [Configuring Message Logging for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-message-log).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Flex Gateway log output, complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://docs.dynatrace.com/docs/discover-dynatrace/get-started/monitoring-environment#environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Flex Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Flex Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.0 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Flex Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Flex Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Restart your Flex Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Flex Gateway in a Kubernetes Cluster

To configure logging for Flex Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Flex Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Flex Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Flex Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

To configure a Message Logging policy, see
[Configuring Message Logging for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-message-log).

Configuring a Message Logging policy makes access logs visible in both API Manager **Logs** and your
third-party log services.

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/1.9/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide#logging)

- [Configuring Message Logging for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-message-log)

- [Disabling Flex Gateway Log Output to Anypoint Platform](https://docs.mulesoft.com/gateway/1.9/flex-conn-disable-logs)

<!-- document id=d8a68ea33238f92f58cab943cb481bd5d590ec699c7bd0c3e12046eb8c95c9a0 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-manage-public-api.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Flex Gateway with the API Manager API Tool

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can configure Flex Gateway in Connected Mode using the API Manager API tool from the
[Anypoint Platform Developer Portal](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/)
instead of using the API Manager user interface through Anypoint Platform. This tool enables you to
use the command line to communicate with API Manager. Use the steps in this tutorial to create,
deploy, apply a policy to, and delete an API instance.

For more information about the API Manager API, see the
[API Manager API documentation](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/).

> [!NOTE] To automate these commands using a Jenkins pipeline, see
> [Automate Flex Gateway in Connected Mode Using a Jenkins Pipeline](https://docs.mulesoft.com/gateway/1.12/flex-conn-jenkins-api).

## Before You Begin

Before you can configure Flex Gateway using the API Manager API, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install).

2.  [Register and Run Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run).

3.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    - Use the **App acts on its behalf (client credentials)** type and include the following scopes:

      - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
        **Deploy API Proxies**

      - Runtime Manager: **Read Servers**

      - Exchange: **Exchange Viewer**

        You do not have to
        [Register and Run Flex Gateway with a Connected App](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run-app) to use the API
        Manager API, but you can use the same Connected App if you include the proper scopes.

    - Save the **Id** and **Secret** of the Connected app you configure.

4.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset you want to create
    or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

5.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Flex Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Flex Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

    - Runtime **Target ID** for the Flex Gateway you want to deploy the API to

      To find the **Target ID**, go to **Anypoint Platform > Runtime Manager > Flex Gateway**.

## Obtain an Authorization token from Access Management

You must obtain an authorization token to make calls using the API Manager API:

1.  Collect the following information:

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

2.  Execute the following request to obtain your Authorization Token after replacing the
    placeholders with the following:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "grant_type": "client_credentials",
     "client_id": "<connected-app-client-id>",
     "client_secret": "<connected-app-client-secret>"
    }'
    ```

3.  Save the returned authorization token.

## Create an API Instance

To create an API instance using the API Manager API:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Flex Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Flex Gateway

    - `<authorization-token>`: Authorization token collected in the
      [Obtain an Authorization token from Access Management](#obtain-an-authorization-token-from-access-management)
      step

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI, a combination of your port and base path for your API instance,
      for example, `http://0.0.0.0:<port-to-populate>/<path>`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "spec": {
       "groupId": "<your-org-id>",
       "assetId": "<asset-id-from-exchange>",
       "version": "<asset-version>"
     },
     "endpoint": {
       "deploymentType": "HY",
       "uri": "<upstream-uri>",
       "proxyUri": "<your-proxy-uri>",
       "isCloudHub": null
     },
     "technology": "flexGateway"
     "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
    }'
    ```

4.  Save the Instance ID, `"id"`, from the response to deploy, apply a policy, or delete the
    instance.

## Deploy an API Instance

To deploy an API instance using the API Manager API:

1.  Collect the following information:

    - `<instance-id>`: Instance ID, `"id"`, from [Create an API Instance](#create-an-api-instance)

    - `<gateway-version>`: Version of Flex Gateway you are using, for example `1.4.0`

    - `<target-id-from-runtime-manager>`: Target ID collected from runtime manager

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/deployments' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: bearer <authorization-token>' \
    --data-raw '{
     "type": "HY",
     "gatewayVersion": "<gateway-version>",
     "targetId": "<target-id-from-runtime-manager>",
     "environmentId": "<your-env-id>"
    }'
    ```

## Apply a Policy

Using the API Manager API, you can only apply Connected Mode policies to a Flex Gateway.

To apply a policy to an API instance using the API Manager API:

1.  Collect the following information:

    - Policy GAV:

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Required configuration parameters for the policy + Each policy has
      unique configuration data fields. The `"username"` and `"password"` fields are an example. To
      find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory).

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/policies' \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
       "configurationData":{
          "username": "user",
          "password": "test"
         },
        "pointcutData":null,
        "assetId": "<policy-asset-id>",
        "assetVersion": "<policy-asset-version>",
        "groupId": "<policy-group-id>"
    }'
    ```

## Delete an API Instance

To delete an API instance using the API Manager API, make a DELETE request to Anypoint Platform
after replacing the sample content:

```ssh
curl --location --request DELETE 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <authorization-token>'
```

## See Also

- [Automating Flex Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.12/flex-conn-jenkins-api)

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

<!-- document id=7d8875408f9fb6246f8bf2fac8e812ae0d1a205230f0648f72ef80a5dd335fbf url=/mulesoft/current/en-us/gateway/1.9/flex-conn-manage-public-api.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Flex Gateway with the API Manager API Tool

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can configure Flex Gateway in Connected Mode using the API Manager API tool from the
[Anypoint Platform Developer Portal](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/)
instead of using the API Manager user interface through Anypoint Platform. This tool enables you to
use the command line to communicate with API Manager. Use the steps in this tutorial to create,
deploy, apply a policy to, and delete an API instance.

For more information about the API Manager API, see the
[API Manager API documentation](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/).

> [!NOTE] To automate these commands using a Jenkins pipeline, see
> [Automate Flex Gateway in Connected Mode Using a Jenkins Pipeline](https://docs.mulesoft.com/gateway/1.9/flex-conn-jenkins-api).

## Before You Begin

Before you can configure Flex Gateway using the API Manager API, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install).

2.  [Register and Run Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run).

3.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    - Use the **App acts on its behalf (client credentials)** type and include the following scopes:

      - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
        **Deploy API Proxies**

      - Runtime Manager: **Read Servers**

      - Exchange: **Exchange Viewer**

        You do not have to
        [Register and Run Flex Gateway with a Connected App](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run-app) to use the API
        Manager API, but you can use the same Connected App if you include the proper scopes.

    - Save the **Id** and **Secret** of the Connected app you configure.

4.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset you want to create
    or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

5.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Flex Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Flex Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

    - Runtime **Target ID** for the Flex Gateway you want to deploy the API to

      To find the **Target ID**, go to **Anypoint Platform > Runtime Manager > Flex Gateway**.

## Obtain an Authorization token from Access Management

You must obtain an authorization token to make calls using the API Manager API:

1.  Collect the following information:

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

2.  Execute the following request to obtain your Authorization Token after replacing the
    placeholders with the following:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "grant_type": "client_credentials",
     "client_id": "<connected-app-client-id>",
     "client_secret": "<connected-app-client-secret>"
    }'
    ```

3.  Save the returned authorization token.

## Create an API Instance

To create an API instance using the API Manager API:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Flex Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Flex Gateway

    - `<authorization-token>`: Authorization token collected in the
      [Obtain an Authorization token from Access Management](#obtain-an-authorization-token-from-access-management)
      step

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI, a combination of your port and base path for your API instance,
      for example, `http://0.0.0.0:<port-to-populate>/<path>`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "spec": {
       "groupId": "<your-org-id>",
       "assetId": "<asset-id-from-exchange>",
       "version": "<asset-version>"
     },
     "endpoint": {
       "deploymentType": "HY",
       "uri": "<upstream-uri>",
       "proxyUri": "<your-proxy-uri>",
       "isCloudHub": null
     },
     "technology": "flexGateway"
     "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
    }'
    ```

4.  Save the Instance ID, `"id"`, from the response to deploy, apply a policy, or delete the
    instance.

## Deploy an API Instance

To deploy an API instance using the API Manager API:

1.  Collect the following information:

    - `<instance-id>`: Instance ID, `"id"`, from [Create an API Instance](#create-an-api-instance)

    - `<gateway-version>`: Version of Flex Gateway you are using, for example `1.4.0`

    - `<target-id-from-runtime-manager>`: Target ID collected from runtime manager

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/deployments' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: bearer <authorization-token>' \
    --data-raw '{
     "type": "HY",
     "gatewayVersion": "<gateway-version>",
     "targetId": "<target-id-from-runtime-manager>",
     "environmentId": "<your-env-id>"
    }'
    ```

## Apply a Policy

Using the API Manager API, you can only apply Connected Mode policies to a Flex Gateway.

To apply a policy to an API instance using the API Manager API:

1.  Collect the following information:

    - Policy GAV:

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Required configuration parameters for the policy + Each policy has
      unique configuration data fields. The `"username"` and `"password"` fields are an example. To
      find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory).

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/policies' \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
       "configurationData":{
          "username": "user",
          "password": "test"
         },
        "pointcutData":null,
        "assetId": "<policy-asset-id>",
        "assetVersion": "<policy-asset-version>",
        "groupId": "<policy-group-id>"
    }'
    ```

## Delete an API Instance

To delete an API instance using the API Manager API, make a DELETE request to Anypoint Platform
after replacing the sample content:

```ssh
curl --location --request DELETE 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <authorization-token>'
```

## See Also

- [Automating Flex Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.9/flex-conn-jenkins-api)

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

<!-- document id=3db4f33d1f8c9a2cbce71be5110e65d9ff9f7155468fb4b64761260c6d08dc2e url=/mulesoft/current/en-us/gateway/1.12/flex-managed-inbound-tls-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Inbound TLS for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Flex Gateway deployed on CloudHub 2.0, the CloudHub 2.0 private space manages the
inbound TLS.

To configure a TLS context for the private space you’re deploying your Managed Flex Gateway to, see
[Configuring Domains and Certificates (TLS Context) for a Private Space](https://docs.mulesoft.com/cloudhub-2/ps-config-domains).

Configuring a TLS context for your private space means all APIs deployed to Managed Flex Gateways in
the private space are HTTPS and secure.

To configure outbound TLS context, see
[Configuring Outbound TLS for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-outbound-tls-config).

<!-- document id=3627f25662eeac026c768d4629e28e3ca7b2cf0f14efe4b0554680eef08be8ec url=/mulesoft/current/en-us/gateway/1.9/flex-managed-inbound-tls-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Inbound TLS for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Flex Gateway deployed on CloudHub 2.0, the CloudHub 2.0 private space manages the
inbound TLS.

To configure a TLS context for the private space you’re deploying your Managed Flex Gateway to, see
[Configuring Domains and Certificates (TLS Context) for a Private Space](https://docs.mulesoft.com/cloudhub-2/ps-config-domains).

Configuring a TLS context for your private space means all APIs deployed to Managed Flex Gateways in
the private space are HTTPS and secure.

To configure outbound TLS context, see
[Configuring Outbound TLS for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-outbound-tls-config).

<!-- document id=2e118ecf3345f7ca7daae0977d2a6304405871e461a95148f4c2b52510d96118 url=/mulesoft/current/en-us/gateway/1.13/managed-inbound-tls-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Inbound TLS for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Omni Gateway deployed on CloudHub 2.0, the CloudHub 2.0 space manages the inbound TLS.

To configure a TLS context for the private space you’re deploying your Managed Omni Gateway to, see
[Configuring Domains and Certificates (TLS Context) for a Private Space](https://docs.mulesoft.com/cloudhub-2/ps-config-domains).
You can’t edit the TLS context for a shared space.

Configuring a TLS context for your private space means all APIs deployed to Managed Omni Gateways in
the private space are HTTPS and secure.

To configure outbound TLS context, see
[Configuring Outbound TLS for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-outbound-tls-config).

<!-- document id=7ba1c498b099a49034f3450afb80c26d4d5f1d9680aca2363587df1cc4ce342a url=/mulesoft/current/en-us/gateway/latest/managed-inbound-tls-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Inbound TLS for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Omni Gateway deployed on CloudHub 2.0, the CloudHub 2.0 space manages the inbound TLS.

To configure a TLS context for the private space you’re deploying your Managed Omni Gateway to, see
[Configuring Domains and Certificates (TLS Context) for a Private Space](https://docs.mulesoft.com/cloudhub-2/ps-config-domains).
You can’t edit the TLS context for a shared space.

Configuring a TLS context for your private space means all APIs deployed to Managed Omni Gateways in
the private space are HTTPS and secure.

To configure outbound TLS context, see
[Configuring Outbound TLS for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-outbound-tls-config).

<!-- document id=b473b127ef008a4a913d6e1589c32129121ebe55858b886a57abd08913ae9d06 url=/mulesoft/current/en-us/gateway/1.12/flex-managed-configure.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configuring Inbound TLS for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-inbound-tls-config) - CloudHub 2.0
  private spaces enable you to protect your API instances with inbound TLS and mTLS.

- [Configuring Outbound TLS for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-outbound-tls-config) - Managed
  Flex Gateway on CloudHub 2.0 enables you to configure TLS and mTLS contexts for each upstream.

- [Configure Timeouts for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-timeout) - Managed Flex Gateway on
  CloudHub 2.0 enables you to configure default timeout settings for your runtime and APIs.

- [Configuring Distributed Tracing for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-tracing-config) - Managed
  Flex Gateway on CloudHub 2.0 enables you to configure distributed tracing.

<!-- document id=d92f61d168dad9985056bc5af3c9f4254e809285870f137cd60852dfab4a0ea2 url=/mulesoft/current/en-us/gateway/1.9/flex-managed-configure.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configuring Inbound TLS for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-inbound-tls-config) - CloudHub 2.0
  private spaces enable you to protect your API instances with inbound TLS and mTLS.

- [Configuring Outbound TLS for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-outbound-tls-config) - Managed
  Flex Gateway on CloudHub 2.0 enables you to configure TLS and mTLS contexts for each upstream.

<!-- document id=f78d51c2db3a99c93eed698adf8a5a4e34b2a4cfacb741dce25f9f4b4a685653 url=/mulesoft/current/en-us/gateway/1.13/managed-configure.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configuring Inbound TLS for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-inbound-tls-config) - CloudHub 2.0
  private spaces enable you to protect your API instances with inbound TLS and mTLS.

- [Configuring Outbound TLS for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-outbound-tls-config) - Managed Omni
  Gateway on CloudHub 2.0 enables you to configure TLS and mTLS contexts for each upstream.

- [Configure Timeouts for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-timeout) - Managed Omni Gateway on CloudHub
  2.0 enables you to configure default timeout settings for your runtime and APIs.

- [Configuring Distributed Tracing for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-tracing-config) - Managed Omni
  Gateway on CloudHub 2.0 enables you to configure distributed tracing.

<!-- document id=4eb2e381b720a504dcbfc794cd2a91d1d5d897b8994140498f2fad491ad95862 url=/mulesoft/current/en-us/gateway/latest/managed-configure.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configuring Inbound TLS for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-inbound-tls-config) - CloudHub 2.0
  private spaces enable you to protect your API instances with inbound TLS and mTLS.

- [Configuring Outbound TLS for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-outbound-tls-config) - Managed Omni
  Gateway on CloudHub 2.0 enables you to configure TLS and mTLS contexts for each upstream.

- [Configure Timeouts for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-timeout) - Managed Omni Gateway on CloudHub
  2.0 enables you to configure default timeout settings for your runtime and APIs.

- [Configuring Distributed Tracing for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-tracing-config) - Managed Omni
  Gateway on CloudHub 2.0 enables you to configure distributed tracing.

<!-- document id=84e348149e083cc22002716e5b6a973c44992949b4515ac8910318ee14760b52 url=/mulesoft/current/en-us/gateway/1.12/policies-mcp-access-control-together.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, mcp, access control, tool mapping, abac
---

# Configuring MCP Access Control Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway provides three MCP policies that work together to control which tools and related MCP
entities are exposed:

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-global-access): Restricts which tools are exposed by
  using allow or block rules.

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-tool-mapping): Redefines tool names and descriptions to
  reduce prompt complexity and improve LLM comprehension.

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-attribute-access-control): Grants each
  client a subset of tools based on who they are, such as Tiers, IP, headers, or claims.

## How the Policies Work Together

You can use MCP policies individually or combine them to fit your use cases. When you use multiple
policies together, stack them in this order from the gateway toward the client so that they work as
intended:

MCP Global Access

Filters the overall tool list. Define rules to allow or block specific tools so that only the tools
you want to expose enter your network.

MCP Tool Mapping

Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension.
Mapping doesn’t filter tools. If you use both policies, MCP Global Access must allow a tool before
mapping applies.

MCP Attribute-Based Access Control

Grants each connecting client a tailored subset of the available tools based on attributes, such as
tiers, IP addresses, headers, or claims.

To configure the policy order, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder).

## See Also

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-global-access)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-tool-mapping)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-attribute-access-control)

- [Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder)

- [Flex Gateway Agent Policies](https://docs.mulesoft.com/gateway/1.12/flex-agent-policies)

<!-- document id=8208cc960cd11fc52eedf6609f9ff13f28ef7c666b1a7bf62d7c705d8b3a263e url=/mulesoft/current/en-us/gateway/1.13/policies-mcp-access-control-together.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, mcp, access control, tool mapping, abac
---

# Configuring MCP Access Control Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides three MCP policies that work together to control which tools and related MCP
entities are exposed:

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-global-access): Restricts which tools are exposed by
  using allow or block rules.

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping): Redefines tool names and descriptions to
  reduce prompt complexity and improve LLM comprehension.

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control): Grants each
  client a subset of tools based on who they are, such as Tiers, IP, headers, or claims.

## How the Policies Work Together

You can use MCP policies individually or combine them to fit your use cases. When you use multiple
policies together, stack them in this order from the gateway toward the client so that they work as
intended:

> [!NOTE] If you use
> [MCP Tools Progressive Disclosure](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-progressive-disclosure), it must be
> positioned after the [MCP Support Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-support) but before any other MCP
> access control policies.

MCP Global Access

Filters the overall tool list. Define rules to allow or block specific tools so that only the tools
you want to expose enter your network.

MCP Tool Mapping

Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension.
Mapping doesn’t filter tools. If you use both policies, MCP Global Access must allow a tool before
mapping applies.

MCP Attribute-Based Access Control

Grants each connecting client a tailored subset of the available tools based on attributes, such as
tiers, IP addresses, headers, or claims.

To configure the policy order, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder).

## See Also

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-global-access)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control)

- [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder)

- [Omni Gateway Agent Policies](https://docs.mulesoft.com/gateway/1.13/agent-policies)

<!-- document id=a5cde3d49725989a1dfcdd95837c4f1dc3082613aa2bf0f1f3529ed980dd33c3 url=/mulesoft/current/en-us/gateway/latest/policies-mcp-access-control-together.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, mcp, access control, tool mapping, abac
---

# Configuring MCP Access Control Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides three MCP policies that work together to control which tools and related MCP
entities are exposed:

- [MCP Global Access](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access): Restricts which tools are exposed by
  using allow or block rules.

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping): Redefines tool names and descriptions to
  reduce prompt complexity and improve LLM comprehension.

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control): Grants each
  client a subset of tools based on who they are, such as Tiers, IP, headers, or claims.

## How the Policies Work Together

You can use MCP policies individually or combine them to fit your use cases. When you use multiple
policies together, stack them in this order from the gateway toward the client so that they work as
intended:

> [!NOTE] If you use
> [MCP Tools Progressive Disclosure](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-progressive-disclosure), it must be
> positioned after the [MCP Support Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support) but before any other MCP
> access control policies.

MCP Global Access

Filters the overall tool list. Define rules to allow or block specific tools so that only the tools
you want to expose enter your network.

MCP Tool Mapping

Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension.
Mapping doesn’t filter tools. If you use both policies, MCP Global Access must allow a tool before
mapping applies.

MCP Attribute-Based Access Control

Grants each connecting client a tailored subset of the available tools based on attributes, such as
tiers, IP addresses, headers, or claims.

To configure the policy order, see [Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder).

## See Also

- [MCP Global Access](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)

- [Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder)

- [Omni Gateway Agent Policies](https://docs.mulesoft.com/gateway/latest/agent-policies)

<!-- document id=3d6259e2e951027cc8cbb1f71ee9ac67fb8c9d58b658831d3db7aebf42ee8bea url=/mulesoft/current/en-us/gateway/1.12/flex-conn-message-log.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Message Logging for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Flex Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-view-api-metrics).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging in Connected Mode

1.  From **API Instances** in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**.

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=5ba5e9234d2df9116f5fe1137d1807336e43a0f5723cc68dd1a7188a46b0eb89 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-message-log.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Message Logging for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Flex Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-view-api-metrics).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging in Connected Mode

1.  From API Administration in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.9/policies-flex-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**.

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=148af692b54da1deed1cf85da786f123642d2910b84f1ad3b22be3152f155656 url=/mulesoft/current/en-us/gateway/1.12/flex-managed-message-log.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Message Logging for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Flex Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-view-api-metrics).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging in Connected Mode

1.  From **API Instances** in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**.

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=3111c78f63d76ecf4c83ed0ca4e7c960b319d09d117844d7c00366fee2bc8653 url=/mulesoft/current/en-us/gateway/1.9/flex-managed-message-log.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Message Logging for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Flex Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-view-api-metrics).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging in Connected Mode

1.  From API Administration in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.9/policies-flex-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**.

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=ff54daa75fd4426e849f13fb4b7f95acc2cfead0f63d49028b2c890e2a01dc60 url=/mulesoft/current/en-us/gateway/1.13/managed-message-log.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Message Logging for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Omni Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-view-api-metrics).

> [!NOTE] To use multiple log levels for different configurations, add multiple configurations
> within a single Message Logging policy. To learn more, see
> [Configuring Multiple Log Levels](#multiple-log-levels).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging

1.  From **API Instances** in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**. For more information about
    configuring multiples levels, see [Configuring Multiple Log Levels](#multiple-log-levels).

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

### Configuring Multiple Log Levels

To log messages at multiple levels or with different conditions within a single Message Logging
policy:

1.  Apply one Message Logging policy to your API instance following the steps at
    [Configure Message Logging](#configure-message-logging).

2.  Configure the first logging entry with your desired settings (for example, **Level**: INFO).

3.  Click **\+ Add** to add another configuration.

4.  Configure the second logging entry with different settings (for example, **Level**: ERROR).

5.  Repeat steps 3-4 to add additional configurations as needed.

6.  Click **Save**.

For example, if you configure the parameter:

- **First configuration**:

  - **Message**: `#[payload]`

  - **Level**: INFO

  - **Before Calling API**: Selected

- **Second configuration**:

  - **Message**: `#[attributes.headers]`

  - **Level**: ERROR

  - **After Calling API**: Selected

This configuration logs the request payload at INFO level before calling the API and logs response
headers at ERROR level after calling the API.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=3d6af1ac881a9a4f7a5eb2d956dab3376a5ec4b56a63412788463dedfcdb040d url=/mulesoft/current/en-us/gateway/latest/managed-message-log.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Message Logging for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Omni Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-view-api-metrics).

> [!NOTE] To use multiple log levels for different configurations, add multiple configurations
> within a single Message Logging policy. To learn more, see
> [Configuring Multiple Log Levels](#multiple-log-levels).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging

1.  From **API Instances** in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**. For more information about
    configuring multiples levels, see [Configuring Multiple Log Levels](#multiple-log-levels).

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

### Configuring Multiple Log Levels

To log messages at multiple levels or with different conditions within a single Message Logging
policy:

1.  Apply one Message Logging policy to your API instance following the steps at
    [Configure Message Logging](#configure-message-logging).

2.  Configure the first logging entry with your desired settings (for example, **Level**: INFO).

3.  Click **\+ Add** to add another configuration.

4.  Configure the second logging entry with different settings (for example, **Level**: ERROR).

5.  Repeat steps 3-4 to add additional configurations as needed.

6.  Click **Save**.

For example, if you configure the parameter:

- **First configuration**:

  - **Message**: `#[payload]`

  - **Level**: INFO

  - **Before Calling API**: Selected

- **Second configuration**:

  - **Message**: `#[attributes.headers]`

  - **Level**: ERROR

  - **After Calling API**: Selected

This configuration logs the request payload at INFO level before calling the API and logs response
headers at ERROR level after calling the API.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=3dec766a7be96069f12748e8361125aea4cf17843b1b08e197cd2aeb1226822e url=/mulesoft/current/en-us/gateway/1.13/conn-message-log.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Message Logging for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Omni Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-view-api-metrics).

> [!NOTE] To use multiple log levels for different configurations, add multiple configurations
> within a single Message Logging policy. To learn more, see
> [Configuring Multiple Log Levels](#multiple-log-levels).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging

1.  From **API Instances** in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**. For more information about
    configuring multiples levels, see [Configuring Multiple Log Levels](#multiple-log-levels).

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

### Configuring Multiple Log Levels

To log messages at multiple levels or with different conditions within a single Message Logging
policy:

1.  Apply one Message Logging policy to your API instance following the steps at
    [Configure Message Logging](#configure-message-logging).

2.  Configure the first logging entry with your desired settings (for example, **Level**: INFO).

3.  Click **\+ Add** to add another configuration.

4.  Configure the second logging entry with different settings (for example, **Level**: ERROR).

5.  Repeat steps 3-4 to add additional configurations as needed.

6.  Click **Save**.

For example, if you configure the parameter:

- **First configuration**:

  - **Message**: `#[payload]`

  - **Level**: INFO

  - **Before Calling API**: Selected

- **Second configuration**:

  - **Message**: `#[attributes.headers]`

  - **Level**: ERROR

  - **After Calling API**: Selected

This configuration logs the request payload at INFO level before calling the API and logs response
headers at ERROR level after calling the API.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=64f4685f37900fccae51b42ae73b88c8237090fefeb2a2bec2ce5af807d4c120 url=/mulesoft/current/en-us/gateway/latest/conn-message-log.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Message Logging for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Applying a Message Logging policy to your API instance in API Manager allows you to view basic logs,
such as inbound and outbound calls and headers, for APIs managed by Omni Gateway within API Manager.
Logging for an API instance only happens if you configure and apply a Message Logging policy.

To view metrics in API Manager, such as total requests, total policy violations, total errors, and
average response time, see
[Viewing Key Metrics in API Manager for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-view-api-metrics).

> [!NOTE] To use multiple log levels for different configurations, add multiple configurations
> within a single Message Logging policy. To learn more, see
> [Configuring Multiple Log Levels](#multiple-log-levels).

## Message Logging Limits and Features

API Manager stores up to 100 MB of logs per API instance for 30 days. Runtime Manager automatically
purges logs that go beyond 100 MB per API instance. If you need more storage, sign up for the
Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform.

Basic logs report this information for each API instance configured through a policy:

- Inbound and outbound API calls, as well as the packet contents

- Headers and any other information in the request

To view message logs in API Manager, you need one of the following permissions:

- API Manager Environment Administrator

- API Manager Deploy API Proxies

- General Organization Administration

Refer to
[Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product).

## Configure Message Logging

1.  From **API Instances** in API Manager, select the name of the API Instance.

2.  Click **Policies**.

3.  Click **\+ Add policy**.

4.  Click **Message Logging** in the **Troubleshooting** category.

5.  Click **Next**.

6.  Click **\+ Add**.

7.  Enter a **Configuration Name**, for example, 'Info messages before calling API'.

8.  Enter a DataWeave expression that selects what information you want to see.

    For example, `#[attributes.headers['id']]` extracts the ids from the headers of the messages.
    For more information, see
    [DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support).

9.  If you want to filter log messages, enter a DataWeave expression.

    For example, `#[attributes.headers['id']==1]` shows log messages that have an id of 1 in the
    header.

10. If you want to affix a prefix to your logs, enter a **Category**.

11. Enter the severity level.

    You can only enter one level. See [Message Logging Severity Levels](#severity-levels) for a
    description of each severity level and the hierarchy for the levels.

12. If you want messages after the API is called, select **After Calling API**.

13. If you want to add additional configurations, click **\+ Add**. For more information about
    configuring multiples levels, see [Configuring Multiple Log Levels](#multiple-log-levels).

14. Click **Save**.

    Afterward, you should see a **Message Log** option for the API instance.

    Use the search field to search for specific logs based on the time and log severity (INFO,
    ERROR, WARN, DEBUG). You can download these logs for further analysis.

### Configuring Multiple Log Levels

To log messages at multiple levels or with different conditions within a single Message Logging
policy:

1.  Apply one Message Logging policy to your API instance following the steps at
    [Configure Message Logging](#configure-message-logging).

2.  Configure the first logging entry with your desired settings (for example, **Level**: INFO).

3.  Click **\+ Add** to add another configuration.

4.  Configure the second logging entry with different settings (for example, **Level**: ERROR).

5.  Repeat steps 3-4 to add additional configurations as needed.

6.  Click **Save**.

For example, if you configure the parameter:

- **First configuration**:

  - **Message**: `#[payload]`

  - **Level**: INFO

  - **Before Calling API**: Selected

- **Second configuration**:

  - **Message**: `#[attributes.headers]`

  - **Level**: ERROR

  - **After Calling API**: Selected

This configuration logs the request payload at INFO level before calling the API and logs response
headers at ERROR level after calling the API.

## Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level.
Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the
INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only
error messages. The following table describes the type of information included in the logs for each
severity level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Log Severity Level</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>DEBUG</p></div></div></td><td><div><div><p>Tracing information used by application developers.</p></div></div></td></tr><tr><td><div><div><p>INFO</p></div></div></td><td><div><div><p>Informational messages that highlight the progress of the application.</p></div></div></td></tr><tr><td><div><div><p>WARN</p></div></div></td><td><div><div><p>Potentially harmful situations that indicate potential problems.</p></div></div></td></tr><tr><td><div><div><p>ERROR</p></div></div></td><td><div><div><p>Events that prevent normal program execution but might allow the application to continue running.</p></div></div></td></tr></tbody></table>

<!-- document id=7c7b5ac62490dd7909f67eac0ebdd0a78ddb5599d6bd92319a6b98e32424b7fb url=/mulesoft/current/en-us/gateway/1.13/gateway-configure.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables configuration via Anypoint Platform or declarative configuration files. You can
configure Omni Gateway running in Connected Mode via both Anypoint Platform or declarative
configuration files, while you can configure Managed Omni Gateway only with Anypoint Platform and
Omni Gateway running in local mode only with configuration files.

Configurations include:

- Replicas

- TLS contexts

- Shared storage

- Forward proxies

- Automated Jenkins pipelines

- Node selection for Kubernetes deployments

For Connected Mode, see [Configuring Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-configure).

For Local Mode, see [Configuring Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-configure).

## See Also

- [Configuring Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-configure)

- [Configuring Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-configure)

- [Configuring Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-configure)

<!-- document id=85c6e30f0a6b27bb3afa3c6d963478ae3d114e4e86bc0b8dde9cb912a71e5002 url=/mulesoft/current/en-us/gateway/latest/gateway-configure.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables configuration via Anypoint Platform or declarative configuration files. You can
configure Omni Gateway running in Connected Mode via both Anypoint Platform or declarative
configuration files, while you can configure Managed Omni Gateway only with Anypoint Platform and
Omni Gateway running in local mode only with configuration files.

Configurations include:

- Replicas

- TLS contexts

- Shared storage

- Forward proxies

- Automated Jenkins pipelines

- Node selection for Kubernetes deployments

For Connected Mode, see [Configuring Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-configure).

For Local Mode, see [Configuring Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-configure).

## See Also

- [Configuring Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-configure)

- [Configuring Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-configure)

- [Configuring Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-configure)

<!-- document id=66d8bd7a7a678c090ea77ad1cf0457d3975a7db9d82846b6eed74fdac582d505 url=/mulesoft/current/en-us/gateway/1.13/conn-replica-caching.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway Configuration Caching in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To reduce scale-up time and increase resiliency, Omni Gateway can cache its gateway configuration in
shared storage. Omni replicas use the cached gateway configuration instead of each replica directly
downloading the configuration from Anypoint Platform. By default, configuration caching is not
enabled.

Omni Gateway configuration caching works by:

1.  After the first Omni replica starts, the replica downloads the configuration from Anypoint
    Platform, encrypts the configuration, and stores it in shared storage.

2.  After subsequent replicas start, they use the locally cached configuration rather than
    downloading from Anypoint Platform.

3.  If the Omni Gateway configuration changes on Anypoint Platform, the replicas download the
    configuration from Anypoint Platform and store it in shared storage for immediate use by the
    other replicas.

    Anytime a configuration is updated, the gateway reloads all local configuration resources.
    Reloading resources doesn’t create any network downtime and only changes the updated
    configuration. However, the gateway logs a runtime `info` message for each resource. To reduce
    logs, adjust your runtime log level.

If caching is configured and shared storage errors occur, each replica downloads configurations
directly from Anypoint Platform. If Omni Gateway disconnects from Anypoint Platform, Omni Gateway
uses the cached configuration until connections are restored.

> [!NOTE] When using distributed shared storage, cached configurations are lost when all replicas go
> down (Managed Gateway is stopped or self-managed is scaled to zero replicas). For persistent
> caching, use [Redis shared storage](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config).

## Enable Omni Gateway Configuration Caching

1.  Make sure shared storage is configured.

    Configure either:

    - [Distributed shared storage](https://docs.mulesoft.com/gateway/1.13/conn-distributed-shared-storage-config): Cached configurations
      are lost when all replicas go down

    - [Redis shared storage](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config): Cached configurations persist when all
      replicas go down

2.  Enable the `FLEX_DATASOURCE_CONTROL_NODE_ENABLED=true` environment variable.

<!-- document id=48bf363b71ef05c19f785365e7b21e05296717be94beed7b26b592bd4209fc9d url=/mulesoft/current/en-us/gateway/latest/conn-replica-caching.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway Configuration Caching in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To reduce scale-up time and increase resiliency, Omni Gateway caches its gateway configuration
instead of each replica directly downloading the configuration from Anypoint Platform.

Configuration caching is enabled by default. To share cached configurations across replicas, you
must configure distributed or Redis shared storage.

If Omni Gateway disconnects from Anypoint Platform, replicas use the cached configuration until
connections are restored.

> [!NOTE] Anytime a configuration is updated, the gateway reloads all local configuration resources.
> Reloading resources doesn’t create any network downtime and only changes the updated
> configuration. However, the gateway logs a runtime `info` message for each resource. To reduce
> logs, adjust your runtime log level.

## Distributed Configuration Caching

When you configure distributed or Redis shared storage, replicas share a single cached configuration
instead of each replica caching its own copy. This reduces load on Anypoint Platform and speeds up
replica startup.

Distributed configuration caching works by:

1.  After the first Omni replica starts, the replica downloads the configuration from Anypoint
    Platform, encrypts the configuration, and stores it in shared storage.

2.  After subsequent replicas start, they use the cached configuration rather than downloading from
    Anypoint Platform.

3.  If the Omni Gateway configuration changes on Anypoint Platform, a replica downloads the
    configuration from Anypoint Platform and stores it in shared storage for immediate use by the
    other replicas.

If caching is configured and shared storage errors occur, each replica downloads configurations
directly from Anypoint Platform.

## Local Filesystem Caching

When no shared storage is configured, Omni Gateway uses the local filesystem storage. Because local
filesystem storage isn’t shared between replicas, each replica caches its own configuration rather
than sharing a cache with other replicas:

1.  When a replica starts, it downloads the configuration from Anypoint Platform, encrypts it, and
    stores it in its local filesystem.

2.  If the replica restarts, it reads the cached configuration from its local filesystem instead of
    downloading it from Anypoint Platform again.

3.  If the Omni Gateway configuration changes on Anypoint Platform, the replica downloads the
    updated configuration and stores it to the local filesystem.

## Enable Omni Gateway Configuration Caching

Configuration caching is enabled by default via the `FLEX_DATASOURCE_CONTROL_NODE_ENABLED`
environment variable, which is set to `true`.

By default, each replica caches its configuration to local filesystem storage. To share cached
configurations across replicas, configure a shared storage resource:

- [Distributed shared storage](https://docs.mulesoft.com/gateway/latest/conn-distributed-shared-storage-config)

- [Redis shared storage](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config)

## Disable Omni Gateway Configuration Caching

To disable configuration caching, set the `FLEX_DATASOURCE_CONTROL_NODE_ENABLED` environment
variable to `false`.

<!-- document id=dd046d62485ef728bfae2515b49eed89e6a2b56a99fe851c468c3637dc5a344b url=/mulesoft/current/en-us/gateway/1.13/conn-tracing-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway Distributed Tracing in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Omni Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Omni Gateway APIs and external
services.

Tracing enables you to track Omni Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Omni Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

Configure distributed tracing in Connected Mode using one of these methods:

- [Runtime Manager runtime configurations](#runtime-manager-config): Applies to all API instances in
  the gateway.

- [Configuration YAML resource](#yaml-resource-config): Applies to all API instances.

- [Policy](#policy-config): Applies to one API instance and provides granular control.

## Before You Begin

To use the OpenTelemetry with Omni Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Configuring Omni Gateway Distributed Tracing in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Distributed Tracing**.

6.  Enable **Distributed tracing**.

7.  Set the **Sampling percentage** to the percentage of transactions to trace.

    To configure sampling only on a per-API basis with the Tracing policy, set **Sampling
    percentage** to `0`.

8.  Apply the changes.

> [!NOTE] The **Sampling percentage** corresponds to the `overall` sampling percentage. The `client`
> and `random` sampling percentages default to `100` when **Sampling percentage** is set to a
> non-zero value.

## Configure with a YAML Resource

Edit and apply a YAML configuration resource to configure distributed tracing for all API instances
in the gateway. Connected Mode supports exporting traces to Anypoint Monitoring, a gRPC
OpenTelemetry endpoint, or an HTTP OpenTelemetry endpoint.

### Export Traces to Anypoint Monitoring

Edit and apply this configuration resource to enable distributed tracing. This configuration
resource applies to all API instances. This example sets global sampling to 0% and policies
configure sampling per API.

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: anypoint
      properties:
        timeout: 10s
    sampling:
      client: 0
      random: 0
      overall: 0
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

### Export Traces to a gRPC OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a gRPC endpoint in Omni, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: h2://splunk-otel-collector-agent.default.svc.cluster.local:4317
        serviceType: grpc
        serviceName: my-flex-name
        timeout: 10s
        resourceAttributes:
          any-key: any-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

### Export Traces to an HTTP OpenTelemetry Endpoint

To configure OpenTelemetry tracing with an HTTP endpoint, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: http://opentelemetry:4318
        tracesUri: http://opentelemetry:4318/v1/traces
        serviceType: http
        serviceName: the-name
        timeout: 10s
        httpHeaders:
          auth: samething
        resourceAttributes:
          nay-key: nay-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Configure Distributed Tracing for Specific APIs

To override the globally configured distributed tracing settings for specific APIs, apply the
Tracing policy. First enable and configure distributed tracing for the gateway, then apply this
policy to the APIs to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-tracing)

## Export Traces from Anypoint Monitoring to Third Parties

To export traces to third-party providers using the Anypoint Monitoring Telemetry Exporter, see
[Exporting Telemetry Data to Third-Party Monitoring Systems](https://docs.mulesoft.com/monitoring/telemetry-exporter).

To export traces using the Anypoint Monitoring Telemetry Exporter, first configure the Telemetry
Exporter in Anypoint Monitoring.

<!-- document id=41ac584427380a1cfc1ad669ef027df1a2287f93743e2fb226a31c3a6aca6e22 url=/mulesoft/current/en-us/gateway/latest/conn-tracing-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway Distributed Tracing in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Omni Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Omni Gateway APIs and external
services.

Tracing enables you to track Omni Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Omni Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

Configure distributed tracing in Connected Mode using one of these methods:

- [Runtime Manager runtime configurations](#runtime-manager-config): Applies to all API instances in
  the gateway.

- [Configuration YAML resource](#yaml-resource-config): Applies to all API instances.

- [Policy](#policy-config): Applies to one API instance and provides granular control.

## Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set,
in this order of precedence:

1.  **Policy**: A policy applied to the API instance.

2.  **Runtime Manager runtime configuration or Configuration resource**: Used if no policy value is
    set.

3.  **Built-in default**: Used if none of the other values is set. A policy value overrides the
    gateway-level value for the API instance it’s applied to. API instances without the policy use
    the gateway-level value.

## Before You Begin

To use the OpenTelemetry with Omni Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Configuring Omni Gateway Distributed Tracing in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Distributed Tracing**.

6.  Enable **Distributed tracing**.

7.  Set the **Sampling percentage** to the percentage of transactions to trace.

    To configure sampling only on a per-API basis with the Tracing policy, set **Sampling
    percentage** to `0`.

8.  Apply the changes.

> [!NOTE] The **Sampling percentage** corresponds to the `overall` sampling percentage. The `client`
> and `random` sampling percentages default to `100` when **Sampling percentage** is set to a
> non-zero value.

## Configure with a YAML Resource

Edit and apply a YAML configuration resource to configure distributed tracing for all API instances
in the gateway. Connected Mode supports exporting traces to Anypoint Monitoring, a gRPC
OpenTelemetry endpoint, or an HTTP OpenTelemetry endpoint.

### Export Traces to Anypoint Monitoring

Edit and apply this configuration resource to enable distributed tracing. This configuration
resource applies to all API instances. This example sets global sampling to 0% and policies
configure sampling per API.

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: anypoint
      properties:
        timeout: 10s
    sampling:
      client: 0
      random: 0
      overall: 0
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

### Export Traces to a gRPC OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a gRPC endpoint in Omni, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: h2://splunk-otel-collector-agent.default.svc.cluster.local:4317
        serviceType: grpc
        serviceName: my-flex-name
        timeout: 10s
        resourceAttributes:
          any-key: any-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

### Export Traces to an HTTP OpenTelemetry Endpoint

To configure OpenTelemetry tracing with an HTTP endpoint, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: http://opentelemetry:4318
        tracesUri: http://opentelemetry:4318/v1/traces
        serviceType: http
        serviceName: the-name
        timeout: 10s
        httpHeaders:
          auth: samething
        resourceAttributes:
          nay-key: nay-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Configure Distributed Tracing for Specific APIs

To override the globally configured distributed tracing settings for specific APIs, apply the
Tracing policy. First enable and configure distributed tracing for the gateway, then apply this
policy to the APIs to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/latest/policies-included-tracing)

## Export Traces from Anypoint Monitoring to Third Parties

To export traces to third-party providers using the Anypoint Monitoring Telemetry Exporter, see
[Exporting Telemetry Data to Third-Party Monitoring Systems](https://docs.mulesoft.com/monitoring/telemetry-exporter).

To export traces using the Anypoint Monitoring Telemetry Exporter, first configure the Telemetry
Exporter in Anypoint Monitoring.

<!-- document id=d18375155bc95d2a0b71d9973029da633c8b73640e322384ec36cc92554ce0d6 url=/mulesoft/current/en-us/gateway/1.13/local-tracing-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway Distributed Tracing in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Omni Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Omni Gateway APIs and external
services.

Tracing enables you to track Omni Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Omni Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

Configure distributed tracing in Local Mode using one of these methods:

- [Configuration YAML resource](#yaml-resource-config): Applies to all API instances.

- [Policy](#policy-config): Applies to one API instance and provides granular control.

## Before You Begin

To use the OpenTelemetry with Omni Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Configure with a YAML Resource

Edit and apply a YAML configuration resource to configure distributed tracing for all API instances
in the gateway. Local Mode supports exporting traces to a gRPC or HTTP OpenTelemetry endpoint.

### Export Traces to a gRPC OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a gRPC endpoint in Omni, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: h2://splunk-otel-collector-agent.default.svc.cluster.local:4317
        serviceType: grpc
        serviceName: my-flex-name
        timeout: 10s
        resourceAttributes:
          any-key: any-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

### Export Traces to an HTTP OpenTelemetry Endpoint

To configure OpenTelemetry tracing with an HTTP endpoint, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: http://opentelemetry:4318
        tracesUri: http://opentelemetry:4318/v1/traces
        serviceType: http
        serviceName: the-name
        timeout: 10s
        httpHeaders:
          auth: samething
        resourceAttributes:
          nay-key: nay-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Configure Distributed Tracing for Specific APIs

To override the globally configured distributed tracing settings for specific APIs, apply the
Tracing policy. First enable and configure distributed tracing for the gateway, then apply this
policy to the APIs to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-tracing)

<!-- document id=f3e798bca4e6ac3986f7515961a1c78d9ba6a5fb5253052cf25882cb15c39d6a url=/mulesoft/current/en-us/gateway/latest/local-tracing-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway Distributed Tracing in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting
telemetry data across distributed systems. Omni Gateway supports OpenTelemetry, enabling you to
configure the generation of distributed tracing data for all API traffic managed by the gateway.
This integration delivers deep visibility into API request flows, making it easier to analyze system
behavior, troubleshoot issues, and understand interactions between Omni Gateway APIs and external
services.

Tracing enables you to track Omni Gateway API interactions. When multiple systems and services are
involved, distributed tracing tracks API requests as they flow through distributed environments,
providing a comprehensive view of the API’s execution.

With the Anypoint Monitoring Telemetry Exporter, you can send Omni Gateway trace data to third-party
observability and analytics platforms, including Azure Monitor, Splunk HEC, or any
OpenTelemetry-compliant tool. This capability allows you to leverage end-to-end observability,
correlating API traces with data from other systems to build a comprehensive view of your
environment.

Configure distributed tracing in Local Mode using one of these methods:

- [Configuration YAML resource](#yaml-resource-config): Applies to all API instances.

- [Policy](#policy-config): Applies to one API instance and provides granular control.

## Before You Begin

To use the OpenTelemetry with Omni Gateway, you must be familiar with:

- Distributed tracing concepts, including traces and spans.

  If you’re new to distributed tracing and OpenTelemetry, we recommend starting with
  [What is OpenTelemetry](https://opentelemetry.io/docs/concepts/what-is-opentelemetry/) and
  [Understanding distributed tracing](https://opentelemetry.io/docs/concepts/observability-primer/#understanding-distributed-tracing).

## Configure with a YAML Resource

Edit and apply a YAML configuration resource to configure distributed tracing for all API instances
in the gateway. Local Mode supports exporting traces to a gRPC or HTTP OpenTelemetry endpoint.

### Export Traces to a gRPC OpenTelemetry Endpoint

To configure OpenTelemetry tracing with a gRPC endpoint in Omni, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: h2://splunk-otel-collector-agent.default.svc.cluster.local:4317
        serviceType: grpc
        serviceName: my-flex-name
        timeout: 10s
        resourceAttributes:
          any-key: any-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

### Export Traces to an HTTP OpenTelemetry Endpoint

To configure OpenTelemetry tracing with an HTTP endpoint, apply this YAML configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: tracing
  namespace: test-ns
spec:
  tracing:
    provider:
      type: opentelemetry
      properties:
        address: http://opentelemetry:4318
        tracesUri: http://opentelemetry:4318/v1/traces
        serviceType: http
        serviceName: the-name
        timeout: 10s
        httpHeaders:
          auth: samething
        resourceAttributes:
          nay-key: nay-value
    sampling:
      client: 100
      random: 100
      overall: 100
    labels:
      - name: c-env-tag
        type: environment
        keyName: FLEX_NAME
        defaultValue: DEFAULT_VAL
      - name: c-header-tag
        type: requestHeader
        keyName: :method
        defaultValue: DEFAULT_METHOD
      - name: c-literal-tag
        type: literal
        defaultValue: the-tag
```

## Configure Distributed Tracing for Specific APIs

To override the globally configured distributed tracing settings for specific APIs, apply the
Tracing policy. First enable and configure distributed tracing for the gateway, then apply this
policy to the APIs to instrument:

- [Tracing Policy](https://docs.mulesoft.com/gateway/latest/policies-included-tracing)

<!-- document id=f34e567858bdf6219c79bf64db8754e1c07936096c0714e7446f679943e80cbe url=/mulesoft/current/en-us/gateway/1.13/conn-configure.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/1.13/conn-rep-run) - Omni Gateway enables you to create replicas, which are
  instances of Omni Gateway. By default, Omni Gateway runs as a single replica. Running multiple
  replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/1.13/conn-tls-config) - Omni Gateway enables you to configure a TLS context to
  support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config) - Omni Gateway enables you to configure
  shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/1.13/conn-forward-proxy) - Omni Gateway enables you to configure a forward
  proxy to route external HTTP connections through a proxy connection.

- [Configure with the API Manager API Tool](https://docs.mulesoft.com/gateway/1.13/conn-manage-public-api) - Omni Gateway enables you to
  configure and manage Omni Gateway via the API Manager API tool, a command-line tool used to
  communicate with API Manager.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/1.13/conn-readiness-liveness) - Omni Gateway enables you to run a liveness
  check command to test gateway health. Additionally, Omni Gateways deployed on Kubernetes include a
  liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/1.13/conn-proxy-protocol) - Omni Gateway supports PROXY protocol to perserve
  client IP address when servicing multi-layer connections.

- [Automate Omni Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/1.13/conn-jenkins-cli) - Omni
  Gateway enables you to build a Jenkins Pipeline by using Anypoint CLI to automate workflows.

- [Automate Omni Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.13/conn-jenkins-api) - Omni
  Gateway enables you to build a Jenkins Pipeline by using the API Manager API to automate
  workflows.

- [Configure Distributed Tracing](https://docs.mulesoft.com/gateway/1.13/conn-tracing-config) - Omni Gateway enables you to configure
  distributed tracing for your APIs.

<!-- document id=1117d3c086dcb2707826c44e23b0c5e673e8e6fc0271adf575609d665a3322e6 url=/mulesoft/current/en-us/gateway/latest/conn-configure.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/latest/conn-rep-run) - Omni Gateway enables you to create replicas, which are
  instances of Omni Gateway. By default, Omni Gateway runs as a single replica. Running multiple
  replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/latest/conn-tls-config) - Omni Gateway enables you to configure a TLS context to
  support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config) - Omni Gateway enables you to configure
  shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/latest/conn-forward-proxy) - Omni Gateway enables you to configure a forward
  proxy to route external HTTP connections through a proxy connection.

- [Configure with the API Manager API Tool](https://docs.mulesoft.com/gateway/latest/conn-manage-public-api) - Omni Gateway enables you to
  configure and manage Omni Gateway via the API Manager API tool, a command-line tool used to
  communicate with API Manager.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/latest/conn-readiness-liveness) - Omni Gateway enables you to run a liveness
  check command to test gateway health. Additionally, Omni Gateways deployed on Kubernetes include a
  liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/latest/conn-proxy-protocol) - Omni Gateway supports PROXY protocol to perserve
  client IP address when servicing multi-layer connections.

- [Automate Omni Gateway with a Jenkins Pipeline using Anypoint CLI](https://docs.mulesoft.com/gateway/latest/conn-jenkins-cli) - Omni
  Gateway enables you to build a Jenkins Pipeline by using Anypoint CLI to automate workflows.

- [Automate Omni Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/latest/conn-jenkins-api) - Omni
  Gateway enables you to build a Jenkins Pipeline by using the API Manager API to automate
  workflows.

- [Configure Distributed Tracing](https://docs.mulesoft.com/gateway/latest/conn-tracing-config) - Omni Gateway enables you to configure
  distributed tracing for your APIs.

<!-- document id=e2a6776aa0955f8d498f6d798d59ac6c6bb6a49c6f50a18b22310a97605d11e5 url=/mulesoft/current/en-us/gateway/1.13/local-configure.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/1.13/local-rep-run) - Omni Gateway enables you to create replicas, which are
  instances of Omni Gateway. By default, Omni Gateway runs as a single replica. Running multiple
  replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/1.13/local-tls-config) - Omni Gateway enables you to configure a TLS context to
  support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/1.13/local-shared-storage-config) - Omni Gateway enables you to configure
  shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/1.13/local-forward-proxy) - Omni Gateway enables you to configure a forward
  proxy to route external HTTP connections through a proxy connection.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/1.13/local-readiness-liveness) - Omni Gateway enables you to run a
  liveness check command to test gateway health. Additionally, Omni Gateways deployed on Kubernetes
  include a liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/1.13/local-proxy-protocol) - Omni Gateway supports PROXY protocol to
  perserve client IP address when servicing multi-layer connections.

- [Configure Distributed Tracing](https://docs.mulesoft.com/gateway/1.13/local-tracing-config) - Omni Gateway enables you to configure
  distributed tracing for your APIs.

Refer to the [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide) for
information about configuring Omni Gateway via declarative configuration files.

<!-- document id=126641fedda515482a6c94c871a0e473d42917109243f79d853163e75f366aa6 url=/mulesoft/current/en-us/gateway/latest/local-configure.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Configure Replicas](https://docs.mulesoft.com/gateway/latest/local-rep-run) - Omni Gateway enables you to create replicas, which are
  instances of Omni Gateway. By default, Omni Gateway runs as a single replica. Running multiple
  replicas enables scaling, load balancing, and high availability.

- [Configure TLS Context](https://docs.mulesoft.com/gateway/latest/local-tls-config) - Omni Gateway enables you to configure a TLS context to
  support regular TLS and mTLS in both inbound and outbound directions.

- [Configure Shared Storage](https://docs.mulesoft.com/gateway/latest/local-shared-storage-config) - Omni Gateway enables you to configure
  shared storage for distributed caching and rate limiting policies.

- [Configure a Forward Proxy](https://docs.mulesoft.com/gateway/latest/local-forward-proxy) - Omni Gateway enables you to configure a forward
  proxy to route external HTTP connections through a proxy connection.

- [Configure a Liveness Check](https://docs.mulesoft.com/gateway/latest/local-readiness-liveness) - Omni Gateway enables you to run a
  liveness check command to test gateway health. Additionally, Omni Gateways deployed on Kubernetes
  include a liveness probe to automatically restart pods after a specified number of failed checks.

- [Configure PROXY Protocol](https://docs.mulesoft.com/gateway/latest/local-proxy-protocol) - Omni Gateway supports PROXY protocol to
  perserve client IP address when servicing multi-layer connections.

- [Configure Distributed Tracing](https://docs.mulesoft.com/gateway/latest/local-tracing-config) - Omni Gateway enables you to configure
  distributed tracing for your APIs.

Refer to the [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide) for
information about configuring Omni Gateway via declarative configuration files.

<!-- document id=90fa0880e929c8441b1f6909b585e46551ed0e74a356ab4c85f65bee16794604 url=/mulesoft/current/en-us/gateway/1.13/conn-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway Log Output for Third-Party Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables you to deliver runtime and access logs to any supported Fluent Bit v3.2.10
output type. You configure log output via a custom YAML file. Additionally, to view access logs, you
must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Omni Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.2.10 output type, such
as `Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Omni Gateway sends
runtime logs to runtime manager and access logs to API Manager. To learn more, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.13/view-logs-in-runtime-manager)

- [Configuring Message Logging for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-message-log).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Omni Gateway log output, complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://www.dynatrace.com/support/help/get-started/monitoring-environment/environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://www.dynatrace.com/support/help/manage/access-control/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Omni Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Omni Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Omni Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Omni Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.13/view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.13/view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Kubernetes Cluster

To configure logging for Omni Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.13/view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Omni Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

To configure a Message Logging policy, see
[Configuring Message Logging for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-message-log).

Configuring a Message Logging policy makes access logs visible in both API Manager **Logs** and your
third-party log services.

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#logging)

- [Configuring Message Logging for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-message-log)

- [Disabling Omni Gateway Log Output to Anypoint Platform](https://docs.mulesoft.com/gateway/1.13/conn-disable-logs)

<!-- document id=6f58a8b2ee0a0a8c81b3ee89fc930b3ca5596273a3c480df1e9dcb315ce404ad url=/mulesoft/current/en-us/gateway/latest/conn-third-party-logs-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway Log Output for Third-Party Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables you to deliver runtime and access logs to any supported Fluent Bit v3.2.10
output type. You configure log output via a custom YAML file. Additionally, to view access logs, you
must also apply a Message Logging policy.

The following configuration file examples demonstrate how to direct Omni Gateway logs to output
types: `File`, `HTTP`, and `Splunk`. However, you can use any Fluent Bit v3.2.10 output type, such
as `Azure Log Analytics`, `Amazon S3`, `Kafka`, and more. For a complete list of Fluent Bit output
types, see the [Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit
version.

As well as being able to configure additional Fluent Bit log output types, Omni Gateway sends
runtime logs to runtime manager and access logs to API Manager. To learn more, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/latest/view-logs-in-runtime-manager)

- [Configuring Message Logging for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-message-log).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Log Output for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Log Output for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Log Output for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Omni Gateway log output, complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

Additionally, depending on your output, ensure that the service where you direct logs to is
operational and that you have the necessary information:

- Splunk:

  - A running [Splunk](https://www.splunk.com/) service. You can test Splunk with a free Splunk
    Cloud trial.

  - Added an HTTP Event Collector (HEC) data input to the Cloud or Enterprise Splunk service. See
    the
    [Splunk documentation](https://docs.splunk.com/Documentation/Splunk/7.0.3/Data/UsetheHTTPEventCollector)
    about how to add a data input, and how to create an HEC token.

- Dynatrace:

  - A running [Dynatrace](https://www.dynatrace.com/) service. You can test Dynatrace with a free
    Dynatrace trial.

  - Environment ID. To find your Dynatrace environment ID, see
    [Environment ID](https://www.dynatrace.com/support/help/get-started/monitoring-environment/environment-id)

  - Access token. To generate a Dynatrace access token, see
    [Access Tokens](https://www.dynatrace.com/support/help/manage/access-control/access-tokens).
    Ensure that the token has the `Ingest logs` token scope.

## Runtime Logs and Access Logs

Runtime and access logs both appear in the same log output. However, you can choose whether to
include both logs in your log output. To use access logs, you must also apply a Message Logging
policy.

### Runtime Logs

Runtime logs include the following information:

- The startup and shutdown of Omni Gateway, Fluent Bit, and Envoy

- Deployed APIs and policies

- Possible misconfigurations of Omni Gateway or other errors

### Access Logs

Access logs describe incoming interaction with Envoy over a period of time and incoming requests and
responses for specific APIs.

To enable access logs, you must apply a Message Logging policy to the API instances you want to
monitor. To apply a Message Logging policy, see [Configuring Access Logs](#configure-access-logs).

## Logging Configuration File

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Omni Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Omni Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

To view configuration files with applied values, see the following configuration file examples:

- [File Configuration Example](#file-configuration-example)

- [HTTP Configuration Example](#http-configuration-example)

- [Splunk Configuration Example](#splunk-configuration-example)

- [Dynatrace Configuration Example](#dynatrace-configuration-example)

## Configure Log Output for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/logs-config.yaml
    ```

2.  Update the file with your desired output configuration details as shown in the following
    examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/latest/view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-logging).

3.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the create and save a YAML file step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Restart your Omni Gateway with an additional volume for the configuration directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

3.  Create and save a YAML file with your desired output configuration details as shown in the
    following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/latest/view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-logging).

4.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## Configure Log Output for Omni Gateway in a Kubernetes Cluster

To configure logging for Omni Gateway:

1.  Create a new resource using a YAML configuration file with your desired output configuration
    details as shown in the following examples:

    - [File Configuration Example](#file-configuration-example)

    - [HTTP Configuration Example](#http-configuration-example)

    - [Splunk Configuration Example](#splunk-configuration-example)

    - [Dynatrace Configuration Example](#dynatrace-configuration-example)

      If no events appear in the logging output, check the Omni Gateway runtime logs for any
      configuration errors.

      To view runtime logs, see
      [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/latest/view-logs-in-runtime-manager).

      For additional troubleshooting help, see
      [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-logging).

2.  If you are configuring access logs, see [Configure Access Logs](#access-logs) to apply a Message
    Logging policy.

## File Configuration Example

Configure Omni Gateway to send formatted runtime and access logs to a file called `log.txt` (Fluent
Bit `File` output), in the `/var/log` directory. As an example, the following definition specifies a
`spec.logging.outputs.type` value of `file`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: file
        parameters:
          file: /var/log/log.txt # Docker: replace `/var/log` with the absolute path to the mounted configuration directory
          format: template
          template: |
            [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

> [!NOTE] For Docker, in `spec.logging.output.parameters.file`, replace `/var/log` with the absolute
> path to the mounted configuration directory.

## HTTP Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a `HTTP` output. As an
example, the following definition specifies a `spec.logging.outputs.type` value of `HTTP`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    outputs:
      - name: default
        type: HTTP
        parameters:
          host: collectors.au.sumologic.com
          port: "443"
          URI: /receiver/v1/http/[PrivateKey]
          format: json_lines
          json_date_key: timestamp
          json_date_format: iso8601
    runtimeLogs:
      logLevel: info
      outputs:
        - default
    accessLogs:
      outputs:
        - default
```

## Splunk Configuration Example

Splunk begins ingesting logs soon after you apply this resource.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: splunk-config
spec:
  logging:
    outputs:
      - name: splunk
        type: splunk
        parameters:
          host: <instance-name>.splunkcloud.com
          port: "8088"
          splunk_token: <Splunk's HEC token>
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs: [splunk]
    accessLogs:
      outputs: [splunk]
```

## Dynatrace Configuration Example

You can configure Omni Gateway to send formatted runtime and access logs to a Dynatrace environment
`HTTP` output. As an example, the following file contains the necessary configurations:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: dynatrace-config
spec:
  logging:
    outputs:
      - name: dynatrace
        type: http
        parameters:
          host: <environmentID>.live.dynatrace.com
          Port: "443"
          allow_duplicated_headers: "false"
          header:
            - Content-Type application/json; charset=utf-8
            - Authorization Api-Token <accessToken>
          URI: /api/v2/logs/ingest
          Format: json
          json_date_key: timestamp
          json_date_format: iso8601
          tls: "on"
          tls.verify: "off"
    runtimeLogs:
      logLevel: info
      outputs:
        - dynatrace
    accessLogs:
      outputs:
        - dynatrace
```

For more information about configuration options, see the
[Fluent Bit documentation](https://docs.fluentbit.io/manual) for your Fluent Bit version.

## Configure Access Logs

To configure access logs in your log output, you must apply a Message Logging policy to the APIs
whose request and response data you want to monitor. If you have previously applied a Message
Logging policy to an API instance, you do not need to configure another.

To configure a Message Logging policy, see
[Configuring Message Logging for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-message-log).

Configuring a Message Logging policy makes access logs visible in both API Manager **Logs** and your
third-party log services.

If your access logs are not visible, it is possible that a policy with a higher execution order is
causing an error before the Message Logging policy can execute. To reorder policy execution, see
[Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder).

## Logging Event Examples

The following log output examples demonstrate possible outputs that may occur for the following
events:

- [Graceful shutdowns](#graceful-shutdowns)

- [Service disconnections](#service-disconnections)

- [Envoy crash](#envoy-crash)

### Graceful Shutdowns

\[flex-gateway-agent\]\[info\] SignalHandler: Signal terminated received
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d):
Stopping with context done \[flex-gateway-agent\]\[info\] XdsService: Stopping with context done
\[flex-gateway-agent\]\[error\] flex-gateway-envoy: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context
canceled \[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] Server dropped connection \[flex-gateway-agent\]\[info\] Agent
communication closed

### Service Disconnections

\[flex-gateway-agent\]\[error\] WebSocket receiver got error: read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Server dropped
connection \[flex-gateway-agent\]\[warn\] Dropped connection due to error read tcp
172.17.0.2:60780->100.64.1.37:443: i/o timeout \[flex-gateway-agent\]\[info\] Reconnecting after
connection was dropped \[flex-gateway-agent\]\[error\] Error connecting to Websocket Server: dial
tcp: lookup arm-mcm2-service.kstg.msap.io on 192.168.65.7:53: dial udp 192.168.65.7:53: connect:
network is unreachable

### Envoy Crash

\[flex-gateway-envoy\]\[critical\] Caught Segmentation fault, suspect faulting address
0xffff87e8fb89485b \[flex-gateway-envoy\]\[critical\] Backtrace (use tools/stack\_decode.py to get
line numbers): \[flex-gateway-envoy\]\[critical\] Envoy version:
36cbae1aeedd8c3b4eb88cd28268d21fe0905ce5/1.23.0/Clean/RELEASE/BoringSSL
\[flex-gateway-envoy\]\[critical\] #0: \_\_restore\_rt \[0x7ff79db2f140\]
\[flex-gateway-envoy\]\[critical\] #1: \[0x557dcfad249b\] \[flex-gateway-envoy\]\[critical\] #2:
\[0x557dcdf35237\] \[flex-gateway-envoy\]\[critical\] #3: \[0x557dce16d49f\]
\[flex-gateway-envoy\]\[critical\] #4: \[0x557dce1a8ff5\] \[flex-gateway-envoy\]\[critical\] #5:
\[0x557dce1a8e47\] \[flex-gateway-envoy\]\[critical\] #6: ... \[flex-gateway-agent\]\[error\]
flex-gateway-envoy: Stopped with error flex-gateway-envoy: command error: signal: segmentation fault
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[error\] flex-gateway-fluent: Stopped with error context canceled
\[flex-gateway-agent\]\[info\] FilesystemWatcher(/etc/mulesoft/flex-gateway/conf.d): Stopping with
context done \[flex-gateway-agent\]\[info\]
FilesystemWatcher(/usr/local/share/mulesoft/flex-gateway/conf.d): Stopping with context done
\[flex-gateway-agent\]\[info\] XdsService: Stopping with context done \[flex-gateway-agent\]\[info\]
Server dropped connection \[flex-gateway-agent\]\[info\] Agent communication closed

## See Also

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#logging)

- [Configuring Message Logging for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-message-log)

- [Disabling Omni Gateway Log Output to Anypoint Platform](https://docs.mulesoft.com/gateway/latest/conn-disable-logs)

<!-- document id=45a232f020f89662db31ea1a416b3fe154641bfdd819061ea3bb6af58cf021e3 url=/mulesoft/current/en-us/gateway/1.13/conn-manage-public-api.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Omni Gateway with the API Manager API Tool

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can configure Omni Gateway in Connected Mode using the API Manager API tool from the
[Anypoint Platform Developer Portal](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/)
instead of using the API Manager user interface through Anypoint Platform. This tool enables you to
use the command line to communicate with API Manager. Use the steps in this tutorial to create,
deploy, apply a policy to, and delete an API instance.

For more information about the API Manager API, see the
[API Manager API documentation](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/).

> [!NOTE] To automate these commands using a Jenkins pipeline, see
> [Automate Omni Gateway in Connected Mode Using a Jenkins Pipeline](https://docs.mulesoft.com/gateway/1.13/conn-jenkins-api).

## Before You Begin

Before you can configure Omni Gateway using the API Manager API, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install).

2.  [Register and Run Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run).

3.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    - Use the **App acts on its behalf (client credentials)** type and include the following scopes:

      - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
        **Deploy API Proxies**

      - Runtime Manager: **Read Servers**

      - Exchange: **Exchange Viewer**

        You do not have to [Register and Run Omni Gateway with a Connected App](https://docs.mulesoft.com/gateway/1.13/conn-reg-run-app) to
        use the API Manager API, but you can use the same Connected App if you include the proper
        scopes.

    - Save the **Id** and **Secret** of the Connected app you configure.

4.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset you want to create
    or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

5.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Omni Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Omni Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

    - Runtime **Target ID** for the Omni Gateway you want to deploy the API to

      To find the **Target ID**, go to **Anypoint Platform > Runtime Manager > Omni Gateway**.

## Obtain an Authorization token from Access Management

You must obtain an authorization token to make calls using the API Manager API:

1.  Collect the following information:

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

2.  Execute the following request to obtain your Authorization Token after replacing the
    placeholders with the following:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "grant_type": "client_credentials",
     "client_id": "<connected-app-client-id>",
     "client_secret": "<connected-app-client-secret>"
    }'
    ```

3.  Save the returned authorization token.

## Create an API Instance

To create an API instance using the API Manager API:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Omni Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Omni Gateway

    - `<authorization-token>`: Authorization token collected in the
      [Obtain an Authorization token from Access Management](#obtain-an-authorization-token-from-access-management)
      step

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI, a combination of your port and base path for your API instance,
      for example, `http://0.0.0.0:<port-to-populate>/<path>`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "spec": {
       "groupId": "<your-org-id>",
       "assetId": "<asset-id-from-exchange>",
       "version": "<asset-version>"
     },
     "endpoint": {
       "deploymentType": "HY",
       "uri": "<upstream-uri>",
       "proxyUri": "<your-proxy-uri>",
       "isCloudHub": null
     },
     "technology": "flexGateway"
     "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
    }'
    ```

4.  Save the Instance ID, `"id"`, from the response to deploy, apply a policy, or delete the
    instance.

## Deploy an API Instance

To deploy an API instance using the API Manager API:

1.  Collect the following information:

    - `<instance-id>`: Instance ID, `"id"`, from [Create an API Instance](#create-an-api-instance)

    - `<gateway-version>`: Version of Omni Gateway you are using, for example `1.4.0`

    - `<target-id-from-runtime-manager>`: Target ID collected from runtime manager

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/deployments' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: bearer <authorization-token>' \
    --data-raw '{
     "type": "HY",
     "gatewayVersion": "<gateway-version>",
     "targetId": "<target-id-from-runtime-manager>",
     "environmentId": "<your-env-id>"
    }'
    ```

## Apply a Policy

Using the API Manager API, you can only apply Connected Mode policies to an Omni Gateway.

To apply a policy to an API instance using the API Manager API:

1.  Collect the following information:

    - Policy GAV:

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Required configuration parameters for the policy + Each policy has
      unique configuration data fields. The `"username"` and `"password"` fields are an example. To
      find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory).

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/policies' \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
       "configurationData":{
          "username": "user",
          "password": "test"
         },
        "pointcutData":null,
        "assetId": "<policy-asset-id>",
        "assetVersion": "<policy-asset-version>",
        "groupId": "<policy-group-id>"
    }'
    ```

## Delete an API Instance

To delete an API instance using the API Manager API, make a DELETE request to Anypoint Platform
after replacing the sample content:

```ssh
curl --location --request DELETE 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <authorization-token>'
```

## See Also

- [Automating Omni Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/1.13/conn-jenkins-api)

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

<!-- document id=2d95c81bf96284d5a8a261b8442ca8d92139b01af72580269ad9fd147c3a423b url=/mulesoft/current/en-us/gateway/latest/conn-manage-public-api.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Omni Gateway with the API Manager API Tool

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can configure Omni Gateway in Connected Mode using the API Manager API tool from the
[Anypoint Platform Developer Portal](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/)
instead of using the API Manager user interface through Anypoint Platform. This tool enables you to
use the command line to communicate with API Manager. Use the steps in this tutorial to create,
deploy, apply a policy to, and delete an API instance.

For more information about the API Manager API, see the
[API Manager API documentation](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/).

> [!NOTE] To automate these commands using a Jenkins pipeline, see
> [Automate Omni Gateway in Connected Mode Using a Jenkins Pipeline](https://docs.mulesoft.com/gateway/latest/conn-jenkins-api).

## Before You Begin

Before you can configure Omni Gateway using the API Manager API, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install).

2.  [Register and Run Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run).

3.  [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app):

    - Use the **App acts on its behalf (client credentials)** type and include the following scopes:

      - API Manager: **Manage APIs Configuration**, **Manage Policies**, **View Policies**, and
        **Deploy API Proxies**

      - Runtime Manager: **Read Servers**

      - Exchange: **Exchange Viewer**

        You do not have to [Register and Run Omni Gateway with a Connected App](https://docs.mulesoft.com/gateway/latest/conn-reg-run-app) to
        use the API Manager API, but you can use the same Connected App if you include the proper
        scopes.

    - Save the **Id** and **Secret** of the Connected app you configure.

4.  Collect the group ID, asset ID, and asset version (GAV) of the Exchange asset you want to create
    or apply.

    To collect your GAV from Exchange:

    1.  Go to Exchange.

    2.  Find the asset to add or apply.

    3.  Collect the group ID and asset ID from the URL.

        For example, the IDs collected from the API Manager API Exchange URL,
        `https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/minor/1.0/pages/home/`,
        are:

        - Group ID: `f1e97bc6-315a-4490-82a7-23abe036327`

        - Asset ID: `api-manager-api`

    4.  Collect the asset version from **Latest Stable**.

        For example, the version collected from the API Gateway HTTP basic authentication policy
        template is `1.3.1`.

5.  Collect the following information from your Anypoint Platform instance:

    - **Organization ID** for the organization where you want to run Omni Gateway

      For more information, see
      [Find Your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id).

    - **Environment ID** for the environment where you want to run Omni Gateway

      For more information, see
      [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like).

    - Runtime **Target ID** for the Omni Gateway you want to deploy the API to

      To find the **Target ID**, go to **Anypoint Platform > Runtime Manager > Omni Gateway**.

## Obtain an Authorization token from Access Management

You must obtain an authorization token to make calls using the API Manager API:

1.  Collect the following information:

    - `<connected-app-client-id>`: **Id** of your connected app

    - `<connected-app-client-secret>`: **Secret** of your connected app

2.  Execute the following request to obtain your Authorization Token after replacing the
    placeholders with the following:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "grant_type": "client_credentials",
     "client_id": "<connected-app-client-id>",
     "client_secret": "<connected-app-client-secret>"
    }'
    ```

3.  Save the returned authorization token.

## Create an API Instance

To create an API instance using the API Manager API:

1.  Collect the following information:

    - `<your-org-id>`: **Organization ID** for the organization where you want to run Omni Gateway

    - `<your-env-id>`: **Environment ID** for the organization where you want to run Omni Gateway

    - `<authorization-token>`: Authorization token collected in the
      [Obtain an Authorization token from Access Management](#obtain-an-authorization-token-from-access-management)
      step

    - API GAV:

      - `<asset-group-id>`: Group ID, obtained from Exchange

      - `<asset-id-from-exchange>`: Asset ID, obtained from Exchange, of the API you want to create

      - `<asset-version>`: Asset version, obtained from Exchange, of the API you want to create

    - `<upstream-uri>`: URI upstream of your API

    - `<your-proxy-uri>`: Proxy URI, a combination of your port and base path for your API instance,
      for example, `http://0.0.0.0:<port-to-populate>/<path>`

2.  Optionally, collect your `"endpointUri"` or remove the `"endpointUri"` field:

    - `<your-consumer-endpoint>`: Consumer endpoint of your API, for example,
      `http://consumer-endpoint.com`

3.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "spec": {
       "groupId": "<your-org-id>",
       "assetId": "<asset-id-from-exchange>",
       "version": "<asset-version>"
     },
     "endpoint": {
       "deploymentType": "HY",
       "uri": "<upstream-uri>",
       "proxyUri": "<your-proxy-uri>",
       "isCloudHub": null
     },
     "technology": "flexGateway"
     "endpointUri": "<your-consumer-endpoint>" // OPTIONAL
    }'
    ```

4.  Save the Instance ID, `"id"`, from the response to deploy, apply a policy, or delete the
    instance.

## Deploy an API Instance

To deploy an API instance using the API Manager API:

1.  Collect the following information:

    - `<instance-id>`: Instance ID, `"id"`, from [Create an API Instance](#create-an-api-instance)

    - `<gateway-version>`: Version of Omni Gateway you are using, for example `1.4.0`

    - `<target-id-from-runtime-manager>`: Target ID collected from runtime manager

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/proxies/xapi/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/deployments' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: bearer <authorization-token>' \
    --data-raw '{
     "type": "HY",
     "gatewayVersion": "<gateway-version>",
     "targetId": "<target-id-from-runtime-manager>",
     "environmentId": "<your-env-id>"
    }'
    ```

## Apply a Policy

Using the API Manager API, you can only apply Connected Mode policies to an Omni Gateway.

To apply a policy to an API instance using the API Manager API:

1.  Collect the following information:

    - Policy GAV:

      - `<policy-group-id>`: Policy group ID from Exchange

      - `<policy-asset-id>`: Policy asset ID from Exchange, for example `http-basic-authentication`

      - `<policy-asset-version>`: Policy asset version from Exchange, for example `1.3.1`

    - `"configurationData"`: Required configuration parameters for the policy + Each policy has
      unique configuration data fields. The `"username"` and `"password"` fields are an example. To
      find the configuration data for your policy, see
      [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory).

2.  Make a POST request to Anypoint Platform after replacing the sample content:

    ```ssh
    curl --location --request POST 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>/policies' \
    --header 'Authorization: bearer <authorization-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
       "configurationData":{
          "username": "user",
          "password": "test"
         },
        "pointcutData":null,
        "assetId": "<policy-asset-id>",
        "assetVersion": "<policy-asset-version>",
        "groupId": "<policy-group-id>"
    }'
    ```

## Delete an API Instance

To delete an API instance using the API Manager API, make a DELETE request to Anypoint Platform
after replacing the sample content:

```ssh
curl --location --request DELETE 'https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<your-org-id>/environments/<your-env-id>/apis/<instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <authorization-token>'
```

## See Also

- [Automating Omni Gateway with a Jenkins Pipeline using the API Manager API](https://docs.mulesoft.com/gateway/latest/conn-jenkins-api)

- [Anypoint Developer API Manager API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/api-manager-api/)

<!-- document id=e4be6ec7a4f1eb47c3b63829692fc4eb91c9cc50e5e2497196879c59b90e1781 url=/mulesoft/current/en-us/gateway/1.12/flex-managed-outbound-tls-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Outbound TLS for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Outbound Transport Layer Security (TLS) encrypts communication between Flex Gateway and upstream
services.

> [!NOTE] Outbound TLS configuration is the same for Managed Flex Gateway and Self-Managed Flex
> Gateway running in Connected Mode. You can use the same TLS contexts across both modes.

After you [create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can
add a TLS context or a mutual authentication TLS (mTLS) context and apply the TLS context to
upstreams in API Manager to encrypt outbound traffic.

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the outbound TLS context for a Managed Flex Gateway, complete the following
tasks:

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## Outbound TLS Configuration Options

You can configure your outbound TLS context to support regular TLS or mTLS.

Refer to the following cross reference table for the required TLS context configuration settings in
the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, create different TLS contexts for the different traffic directions
of your API instance. You can also use the same TLS context to support different traffic directions,
but you can’t support TLS and mTLS for the same direction by using the same context. Include the
required parameters for both directions if you use the same TLS context for different directions.

## Add a TLS Context for Flex Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and keystore
or truststore. You can also add context expiration date and ALPN Protocols and configure the
outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy each API instance to apply the changes. To redeploy API instances,
> see [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  To apply your TLS context to API instances, make your secret group downloadable.

    To make your secret group downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**.

    3.  If **Secret Group Downloadable** is not selected, select it and click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and then click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Flex Gateway** to use the TLS context as the SSL validation for Flex Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      Support a range of TLS versions or a single version by selecting the same version for the
      minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, select the PEM type keystore to store in the TLS context.
      The keystore contains the certificate presented by Flex Gateway to the remote party for
      outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, select a PEM type truststore to store certificates
      trusted by the client. The truststore contains the CA path that Flex uses to validate the
      remote party certificate for outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Flex Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Outbound Settings**  
      If you don’t want to support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an upstream service when configuring the upstream configuration of a
new API instance or by editing an existing instance’s upstream configuration.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context to an upstream service:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Configure the upstream service, if adding a new API instance.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

<!-- document id=f8e1daea136233e67c112710329c250f9f7b9051f436afb2fcb2d298615cd145 url=/mulesoft/current/en-us/gateway/1.9/flex-managed-outbound-tls-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Outbound TLS for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Outbound Transport Layer Security (TLS) encrypts communication between Flex Gateway and upstream
services.

> [!NOTE] Outbound TLS configuration is the same for Managed Flex Gateway and Self-Managed Flex
> Gateway running in Connected Mode. You can use the same TLS contexts across both modes.

After you [create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can
add a TLS context or a mutual authentication TLS (mTLS) context and apply the TLS context to
upstreams in API Manager to encrypt outbound traffic.

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the outbound TLS context for a Managed Flex Gateway, complete the following
tasks:

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## Outbound TLS Configuration Options

You can configure your outbound TLS context to support regular TLS or mTLS.

Refer to the following cross reference table for the required TLS context configuration settings in
the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, create different TLS contexts for the different traffic directions
of your API instance. You can also use the same TLS context to support different traffic directions,
but you can’t support TLS and mTLS for the same direction by using the same context. Include the
required parameters for both directions if you use the same TLS context for different directions.

## Add a TLS Context for Flex Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and keystore
or truststore. You can also add context expiration date and ALPN Protocols and configure the
outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy each API instance to apply the changes. To redeploy API instances,
> see [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  To apply your TLS context to API instances, make your secret group downloadable.

    To make your secret group downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**.

    3.  If **Secret Group Downloadable** is not selected, select it and click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and then click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Flex Gateway** to use the TLS context as the SSL validation for Flex Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      Support a range of TLS versions or a single version by selecting the same version for the
      minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, select the PEM type keystore to store in the TLS context.
      The keystore contains the certificate presented by Flex Gateway to the remote party for
      outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, select a PEM type truststore to store certificates
      trusted by the client. The truststore contains the CA path that Flex uses to validate the
      remote party certificate for outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Flex Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Outbound Settings**  
      If you don’t want to support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an upstream service when configuring the upstream configuration of a
new API instance or by editing an existing instance’s upstream configuration.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context to an upstream service:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Configure the upstream service, if adding a new API instance.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

<!-- document id=3cd0e7cec97919c61d84c3cdd944bfa95c5faaab27d0e6a05c71c8f93cb79622 url=/mulesoft/current/en-us/gateway/1.13/managed-outbound-tls-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Outbound TLS for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Outbound Transport Layer Security (TLS) encrypts communication between Omni Gateway and upstream
services.

> [!NOTE] Outbound TLS configuration is the same for Managed Omni Gateway and Self-Managed Omni
> Gateway running in Connected Mode. You can use the same TLS contexts across both modes.

After you [create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can
add a TLS context or a mutual authentication TLS (mTLS) context and apply the TLS context to
upstreams in API Manager to encrypt outbound traffic.

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the outbound TLS context for a Managed Omni Gateway, complete the following
tasks:

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## Outbound TLS Configuration Options

You can configure your outbound TLS context to support regular TLS or mTLS.

Refer to the following cross reference table for the required TLS context configuration settings in
the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, create different TLS contexts for the different traffic directions
of your API instance. You can also use the same TLS context to support different traffic directions,
but you can’t support TLS and mTLS for the same direction by using the same context. Include the
required parameters for both directions if you use the same TLS context for different directions.

## Add a TLS Context for Omni Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and keystore
or truststore. You can also add context expiration date and ALPN Protocols and configure the
outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy each API instance to apply the changes. To redeploy API instances,
> see [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  To apply your TLS context to API instances, make your secret group downloadable.

    To make your secret group downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**.

    3.  If **Secret Group Downloadable** is not selected, select it and click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and then click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Omni Gateway** to use the TLS context as the SSL validation for Omni Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      Support a range of TLS versions or a single version by selecting the same version for the
      minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, select the PEM type keystore to store in the TLS context.
      The keystore contains the certificate presented by Omni Gateway to the remote party for
      outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, select a PEM type truststore to store certificates
      trusted by the client. The truststore contains the CA path that Omni uses to validate the
      remote party certificate for outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Omni Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Outbound Settings**  
      If you don’t want to support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an upstream service when configuring the upstream configuration of a
new API instance or by editing an existing instance’s upstream configuration.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context to an upstream service:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Configure the upstream service, if adding a new API instance.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

<!-- document id=b9c2f3325c4659b8f606680a40c9d231b4136224e5eec1a74b4c684f9b2ed44f url=/mulesoft/current/en-us/gateway/latest/managed-outbound-tls-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Outbound TLS for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Outbound Transport Layer Security (TLS) encrypts communication between Omni Gateway and upstream
services.

> [!NOTE] Outbound TLS configuration is the same for Managed Omni Gateway and Self-Managed Omni
> Gateway running in Connected Mode. You can use the same TLS contexts across both modes.

After you [create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can
add a TLS context or a mutual authentication TLS (mTLS) context and apply the TLS context to
upstreams in API Manager to encrypt outbound traffic.

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the outbound TLS context for a Managed Omni Gateway, complete the following
tasks:

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## Outbound TLS Configuration Options

You can configure your outbound TLS context to support regular TLS or mTLS.

Refer to the following cross reference table for the required TLS context configuration settings in
the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, create different TLS contexts for the different traffic directions
of your API instance. You can also use the same TLS context to support different traffic directions,
but you can’t support TLS and mTLS for the same direction by using the same context. Include the
required parameters for both directions if you use the same TLS context for different directions.

## Add a TLS Context for Omni Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and keystore
or truststore. You can also add context expiration date and ALPN Protocols and configure the
outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy each API instance to apply the changes. To redeploy API instances,
> see [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  To apply your TLS context to API instances, make your secret group downloadable.

    To make your secret group downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**.

    3.  If **Secret Group Downloadable** is not selected, select it and click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and then click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Omni Gateway** to use the TLS context as the SSL validation for Omni Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      Support a range of TLS versions or a single version by selecting the same version for the
      minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, select the PEM type keystore to store in the TLS context.
      The keystore contains the certificate presented by Omni Gateway to the remote party for
      outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, select a PEM type truststore to store certificates
      trusted by the client. The truststore contains the CA path that Omni uses to validate the
      remote party certificate for outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Omni Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Outbound Settings**  
      If you don’t want to support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an upstream service when configuring the upstream configuration of a
new API instance or by editing an existing instance’s upstream configuration.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context to an upstream service:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Configure the upstream service, if adding a new API instance.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

<!-- document id=95eb7b2a5388b696638624c8d02626fe310af7c891ba11ad0370cd7806999c3d url=/mulesoft/current/en-us/gateway/1.12/flex-conn-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring PROXY Protocol in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Flex Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Flex Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Flex Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

## Enable PROXY Protocol for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster

To configure PROXY protocol for Flex Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=e9c2bc8a99150d709907ce9f93b3af2f32ef08d06870bfb600b64ab032571d11 url=/mulesoft/current/en-us/gateway/1.13/conn-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring PROXY Protocol in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Omni Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Omni Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Omni Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

## Enable PROXY Protocol for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster

To configure PROXY protocol for Omni Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=8fdcc6cd31d262123aedcb89f4927a840ae7f1f6cce8562363e3ae0fcd6da2f5 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring PROXY Protocol in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Flex Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Flex Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Flex Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

## Enable PROXY Protocol for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster

To configure PROXY protocol for Flex Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=efadb044ce9be960460b6810f80ebcc6421948ce5d3e7266ff14db005308479c url=/mulesoft/current/en-us/gateway/latest/conn-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring PROXY Protocol in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Omni Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Omni Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Omni Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

## Enable PROXY Protocol for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster

To configure PROXY protocol for Omni Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=ba4a6f9522c160f08a498ec599da832a998d6066948e0bb5f87ca998f7633769 url=/mulesoft/current/en-us/gateway/1.12/flex-local-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring PROXY Protocol in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Flex Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Flex Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Flex Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

## Enable PROXY Protocol for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster

To configure PROXY protocol for Flex Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=cab6de0b82473b82ce7014903084da3058052ae583a9b117489441811d44e907 url=/mulesoft/current/en-us/gateway/1.13/local-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring PROXY Protocol in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Omni Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Omni Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Omni Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

## Enable PROXY Protocol for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster

To configure PROXY protocol for Omni Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=5c446bdabfce77096baa8125a0cfba56db0f0f51f7e8dbfdea5645134e1a643f url=/mulesoft/current/en-us/gateway/1.9/flex-local-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring PROXY Protocol in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Flex Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Flex Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Flex Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

## Enable PROXY Protocol for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Flex Gateway in a Kubernetes Cluster

To configure PROXY protocol for Flex Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=c3812e1b165a772918079e505188868ac1a4b715ca7941809c742b91858bf4b6 url=/mulesoft/current/en-us/gateway/latest/local-proxy-protocol.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring PROXY Protocol in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For use cases when Omni Gateway is deployed behind a load balancer or other proxy service, configure
PROXY protocol to preserve client IP addresses across multiple layers of NAT or TCP proxies.

In PROXY protocol, the load balancer or other proxy service sends the PROXY protocol header
containing the client address and additional information to Omni Gateway. To learn more about PROXY
protocol, see the
[HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).

Enabling PROXY protocol only enables Omni Gateway to receive the PROXY protocol header. Your load
balancer or other proxy service must support PROXY protocol to transmit the header.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Enable PROXY Protocol for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Enable PROXY Protocol for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before enabling PROXY protocol for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/local-reg-run)

## Enable PROXY Protocol for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/proxy-protocol-config.yaml
    ```

2.  Update the file with the PROXY protocol configuration file:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your PROXY protocol
    configuration details.

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: config
    spec:
      proxyProtocol:
        enabled: true
    ```

## Enable PROXY Protocol for Omni Gateway in a Kubernetes Cluster

To configure PROXY protocol for Omni Gateway, create a new resource using a YAML configuration file
with your PROXY protocol details.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: config
spec:
  proxyProtocol:
    enabled: true
```

## See Also

- [HAProxy specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)

<!-- document id=19a3bb307268e92667030e9d0439640ec2e5103a7e70856364b1e36849265459 url=/mulesoft/current/en-us/gateway/1.13/conn-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Redis Shared Storage for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable [Redis](https://redis.io/) shared storage for distributed caching, gateway configuration
caching (Connected Mode), and rate limiting policies.

Configure Redis shared storage if persistent storage is required when all replicas go down (scaled
to zero replicas). If persistent shared storage isn’t required,
[configure distributed shared storage](https://docs.mulesoft.com/gateway/1.13/conn-distributed-shared-storage-config).

You configure shared storage via a storage YAML file.

The following steps demonstrate Redis-based storage support for Omni Gateway running in a Docker
container, as a Linux service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, see:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Omni Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-shared-storage-config)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#shared-storage)

<!-- document id=386a4b740fa2de206d499829e841d028c050b199f9aa132912a66d7a5a5ba011 url=/mulesoft/current/en-us/gateway/latest/conn-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Redis Shared Storage for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable [Redis](https://redis.io/) shared storage for distributed caching, gateway configuration
caching (Connected Mode), and rate limiting policies.

Configure Redis shared storage if persistent storage is required when all replicas go down (scaled
to zero replicas). If persistent shared storage isn’t required,
[configure distributed shared storage](https://docs.mulesoft.com/gateway/latest/conn-distributed-shared-storage-config).

You configure shared storage via a storage YAML file.

The following steps demonstrate Redis-based storage support for Omni Gateway running in a Docker
container, as a Linux service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, see:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Omni Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-shared-storage-config)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#shared-storage)

<!-- document id=c3236138cc5c93af54bd58093aaeb87c528c3ce420bbfbb66616e7d28b7f4cab url=/mulesoft/current/en-us/gateway/1.13/local-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Redis Shared Storage for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable [Redis](https://redis.io/) shared storage for distributed caching, gateway configuration
caching (Connected Mode), and rate limiting policies.

Configure Redis shared storage if persistent storage is required when all replicas go down (scaled
to zero replicas). If persistent shared storage isn’t required,
[configure distributed shared storage](https://docs.mulesoft.com/gateway/1.13/local-distributed-shared-storage-config).

You configure shared storage via a storage YAML file.

The following steps demonstrate Redis-based storage support for Omni Gateway running in a Docker
container, as a Linux service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, see:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Omni Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config)

- [Declarative Configuration Reference](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#shared-storage)

<!-- document id=f132f75e28c94fd6cc4ba2488ad3a9e0ecd1bf6b7ecc80ab688736535d4351aa url=/mulesoft/current/en-us/gateway/latest/local-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Redis Shared Storage for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable [Redis](https://redis.io/) shared storage for distributed caching, gateway configuration
caching (Connected Mode), and rate limiting policies.

Configure Redis shared storage if persistent storage is required when all replicas go down (scaled
to zero replicas). If persistent shared storage isn’t required,
[configure distributed shared storage](https://docs.mulesoft.com/gateway/latest/local-distributed-shared-storage-config).

You configure shared storage via a storage YAML file.

The following steps demonstrate Redis-based storage support for Omni Gateway running in a Docker
container, as a Linux service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, see:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Omni Gateway as a Linux service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Omni Gateway, complete the following tasks:

1.  [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

2.  [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/local-reg-run)

## Configure Shared Storage for Omni Gateway as a Linux service

1.  Create a folder in the `/usr/local/share/mulesoft/flex-gateway/conf.d` directory and name it
    `storage`:

    ```ssh
    sudo mkdir /usr/local/share/mulesoft/flex-gateway/conf.d/storage
    ```

2.  Create a YAML configuration file in the `storage` folder:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/storage/shared-storage-config.yaml
    ```

4.  Apply this configuration to all Omni Gateway replicas for them to share data. Sample
    configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to the last step.

1.  Stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

5.  Apply this configuration to all Omni Gateway replicas for them to share data.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Omni Gateway in a Kubernetes Cluster

1.  Create a new resource using a YAML configuration file with your storage details.

2.  Apply this configuration to all Omni Gateway replicas for them to share data.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Omni Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config)

- [Declarative Configuration Reference](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#shared-storage)

<!-- document id=b1c0c02294e4cb9006eaf03f0413b433262f0845a142a81b266234e09b506ae9 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-rep-run.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Replicas for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-a-flex-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-a-flex-replica-as-a-linux-service">Add a Flex Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add a Flex Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Flex Replicas

A Flex Replica is an instance of Flex Gateway. Setting up your gateway layer with multiple Flex
Gateway replicas enables the APIs deployed on Flex Gateway to serve more traffic.

When using Flex Gateway to manage APIs in production, configure more than one Flex Replica to avoid
a single point of failure. Running multiple Flex Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Register and Run in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

## Add a Flex Replica as a Linux Service

Adding a Flex Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Flex Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

Now if you check in Runtime Manager after clicking **Flex Gateway** in the left navigation, your
Flex Gateway will have an additional replica listed. You may need to refresh the page.

## Add a Flex Replica in a Docker Container

To add a Flex Replica in a Docker Container you must run the Flex Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

Now if you check in Runtime Manager after clicking **Flex Gateway** in the left navigation, your
Flex Gateway will have an additional replica listed. You may need to refresh the page.

<!-- document id=31975db0b0ecb0b8a5e87cd5fe1f26e58298fedb25f5ea655e3f7d714c8b2b20 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-rep-run.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Replicas for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-a-flex-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-a-flex-replica-as-a-linux-service">Add a Flex Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add a Flex Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Flex Replicas

A Flex Replica is an instance of Flex Gateway. Setting up your gateway layer with multiple Flex
Gateway replicas enables the APIs deployed on Flex Gateway to serve more traffic.

When using Flex Gateway to manage APIs in production, configure more than one Flex Replica to avoid
a single point of failure. Running multiple Flex Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- [Register and Run in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

## Add a Flex Replica as a Linux Service

Adding a Flex Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Flex Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

Now if you check in Runtime Manager after clicking **Flex Gateway** in the left navigation, your
Flex Gateway will have an additional replica listed. You may need to refresh the page.

## Add a Flex Replica in a Docker Container

To add a Flex Replica in a Docker Container you must run the Flex Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

Now if you check in Runtime Manager after clicking **Flex Gateway** in the left navigation, your
Flex Gateway will have an additional replica listed. You may need to refresh the page.

<!-- document id=a7d6a37684b8e9d91209bff756c3b2b6ae73d3aecdaf0d19774ae491fad5d523 url=/mulesoft/current/en-us/gateway/1.12/flex-local-rep-run.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Replicas for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-a-flex-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-a-flex-replica-as-a-linux-service">Add a Flex Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add a Flex Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Flex Replicas

A Flex Replica is an instance of Flex Gateway. Setting up your gateway layer with multiple Flex
Gateway replicas enables the APIs deployed on Flex Gateway to serve more traffic.

When using Flex Gateway to manage APIs in production, configure more than one Flex Replica to avoid
a single point of failure. Running multiple Flex Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

## Add a Flex Replica as a Linux Service

Adding a Flex Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Flex Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Add a Flex Replica in a Docker Container

To add a Flex Replica in a Docker Container you must run the Flex Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

<!-- document id=e3afe6a8236a3ee0580192f6e831918df5395bdf8f464d672a25bf12488a533b url=/mulesoft/current/en-us/gateway/1.9/flex-local-rep-run.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Replicas for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-a-flex-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-a-flex-replica-as-a-linux-service">Add a Flex Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add a Flex Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Flex Replicas

A Flex Replica is an instance of Flex Gateway. Setting up your gateway layer with multiple Flex
Gateway replicas enables the APIs deployed on Flex Gateway to serve more traffic.

When using Flex Gateway to manage APIs in production, configure more than one Flex Replica to avoid
a single point of failure. Running multiple Flex Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

## Add a Flex Replica as a Linux Service

Adding a Flex Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Flex Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Add a Flex Replica in a Docker Container

To add a Flex Replica in a Docker Container you must run the Flex Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

<!-- document id=c3c3e47e55f9aa8ab7abd022df15c35106eaf60183a2b465da81d6ba79665fb7 url=/mulesoft/current/en-us/gateway/1.13/conn-rep-run.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Replicas for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-an-omni-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-an-omni-replica-as-a-linux-service">Add an Omni Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add an Omni Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Omni Replicas

An Omni Replica is an instance of Omni Gateway. Setting up your gateway layer with multiple Omni
Gateway replicas enables the APIs deployed on Omni Gateway to serve more traffic.

When using Omni Gateway to manage APIs in production, configure more than one Omni Replica to avoid
a single point of failure. Running multiple Omni Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- [Register and Run in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

## Add an Omni Replica as a Linux Service

Adding an Omni Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Omni Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

Now if you check in Runtime Manager after clicking **Omni Gateway** in the left navigation, your
Omni Gateway will have an additional replica listed. You may need to refresh the page.

## Add an Omni Replica in a Docker Container

To add an Omni Replica in a Docker Container you must run the Omni Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

Now if you check in Runtime Manager after clicking **Omni Gateway** in the left navigation, your
Omni Gateway will have an additional replica listed. You may need to refresh the page.

<!-- document id=c8d9197a1c5b8df2ee25df7439ce5e56ececf27df719a903d9ca26ef10de78aa url=/mulesoft/current/en-us/gateway/latest/conn-rep-run.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Replicas for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-an-omni-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-an-omni-replica-as-a-linux-service">Add an Omni Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add an Omni Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Omni Replicas

An Omni Replica is an instance of Omni Gateway. Setting up your gateway layer with multiple Omni
Gateway replicas enables the APIs deployed on Omni Gateway to serve more traffic.

When using Omni Gateway to manage APIs in production, configure more than one Omni Replica to avoid
a single point of failure. Running multiple Omni Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- [Register and Run in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

## Add an Omni Replica as a Linux Service

Adding an Omni Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Omni Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

Now if you check in Runtime Manager after clicking **Omni Gateway** in the left navigation, your
Omni Gateway will have an additional replica listed. You may need to refresh the page.

## Add an Omni Replica in a Docker Container

To add an Omni Replica in a Docker Container you must run the Omni Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

Now if you check in Runtime Manager after clicking **Omni Gateway** in the left navigation, your
Omni Gateway will have an additional replica listed. You may need to refresh the page.

<!-- document id=32d3567d347d01ff2bceec95aa5c9da4e6c734bde9002505e0d91fc8c9ce8329 url=/mulesoft/current/en-us/gateway/1.13/local-rep-run.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Replicas for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-an-omni-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-an-omni-replica-as-a-linux-service">Add an Omni Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add an Omni Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Omni Replicas

An Omni Replica is an instance of Omni Gateway. Setting up your gateway layer with multiple Omni
Gateway replicas enables the APIs deployed on Omni Gateway to serve more traffic.

When using Omni Gateway to manage APIs in production, configure more than one Omni Replica to avoid
a single point of failure. Running multiple Omni Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

## Add an Omni Replica as a Linux Service

Adding an Omni Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Omni Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Add an Omni Replica in a Docker Container

To add an Omni Replica in a Docker Container you must run the Omni Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

<!-- document id=6de854453c5ea833a84c952ca2c11defd39b1cc79c5cf9ce7ec386fb170be82f url=/mulesoft/current/en-us/gateway/latest/local-rep-run.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Replicas for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#add-an-omni-replica-as-a-linux-service"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#add-an-omni-replica-as-a-linux-service">Add an Omni Replica as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Add an Omni Replica in a Docker Container</a></p></div></div></td></tr></tbody></table>

## Omni Replicas

An Omni Replica is an instance of Omni Gateway. Setting up your gateway layer with multiple Omni
Gateway replicas enables the APIs deployed on Omni Gateway to serve more traffic.

When using Omni Gateway to manage APIs in production, configure more than one Omni Replica to avoid
a single point of failure. Running multiple Omni Replicas also increases performance if your API
service receives a significant amount of traffic.

## Before You Begin

Before getting started, ensure you have completed the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

## Add an Omni Replica as a Linux Service

Adding an Omni Replica as a Linux Service includes the following tasks:

- Copy and paste the registration file created during registration to your Linux machine or VM.

- Run the Omni Gateway start command.

### Copy the Registration File

Copy the `registration.yaml` file to the following location on your Linux machine or VM:

- `/usr/local/share/mulesoft/flex-gateway/conf.d`

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Add an Omni Replica in a Docker Container

To add an Omni Replica in a Docker Container you must run the Omni Gateway start command using the
same `registration.yaml` file created during registration. If you are running the container locally,
you will also need to use a different port.

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

<!-- document id=533dec2d4332ff94554ee3834a33ab706c89bc1b579cb98a50451b84f1f5c2b3 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Shared Storage for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable shared storage for distributed caching, gateway configuration caching (Connected Mode), and
rate limiting policies. Redis also provides extra memory for caching.

Production workflows should use [Redis](https://redis.io/). If Redis is not defined, shared storage
services at port 4000 are still available but use an in-memory implementation. You must configure
Redis for distributed policies to share data. All other policies use replica memory for storage.

You configure shared storage via a custom YAML file.

The following steps demonstrate Redis-based storage support for Flex Gateway running in a Docker
container, as a Linux Service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, refer to:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

## Configure Shared Storage for Flex Gateway as a Linux Service

1.  Create a folder in the `/etc/mulesoft/flex-gateway/conf.d` directory and name it `custom`:

    ```ssh
    sudo mkdir /etc/mulesoft/flex-gateway/conf.d/custom
    ```

2.  Create a YAML configuration file in the `custom` folder:

    ```ssh
    sudo touch /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Kubernetes Cluster

To configure shared storage for Flex Gateway, create a new resource using a YAML configuration file
with your storage details.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Flex Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-shared-storage-config)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide#shared-storage)

<!-- document id=8e04192b1b872cb0ef7bf679c587efe7cc540667df2efcfcf66c23c5658edbc7 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Shared Storage for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable shared storage for distributed caching, gateway configuration caching (Connected Mode), and
rate limiting policies. Redis also provides extra memory for caching.

Production workflows should use [Redis](https://redis.io/). If Redis is not defined, shared storage
services at port 4000 are still available but use an in-memory implementation. You must configure
Redis for distributed policies to share data. All other policies use replica memory for storage.

You configure shared storage via a custom YAML file.

The following steps demonstrate Redis-based storage support for Flex Gateway running in a Docker
container, as a Linux Service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, refer to:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

## Configure Shared Storage for Flex Gateway as a Linux Service

1.  Create a folder in the `/etc/mulesoft/flex-gateway/conf.d` directory and name it `custom`:

    ```ssh
    sudo mkdir /etc/mulesoft/flex-gateway/conf.d/custom
    ```

2.  Create a YAML configuration file in the `custom` folder:

    ```ssh
    sudo touch /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Kubernetes Cluster

To configure shared storage for Flex Gateway, create a new resource using a YAML configuration file
with your storage details.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Flex Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-shared-storage-config)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide#shared-storage)

<!-- document id=067c11fcbc0056b5692a3aba4cb75d79079d79bf09ac89bbf11bbfb5167a2103 url=/mulesoft/current/en-us/gateway/1.12/flex-local-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Shared Storage for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable shared storage for distributed caching, gateway configuration caching (Connected Mode), and
rate limiting policies. Redis also provides extra memory for caching.

Production workflows should use [Redis](https://redis.io/). If Redis is not defined, shared storage
services at port 4000 are still available but use an in-memory implementation. You must configure
Redis for distributed policies to share data. All other policies use replica memory for storage.

You configure shared storage via a custom YAML file.

The following steps demonstrate Redis-based storage support for Flex Gateway running in a Docker
container, as a Linux Service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, refer to:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

## Configure Shared Storage for Flex Gateway as a Linux Service

1.  Create a folder in the `/etc/mulesoft/flex-gateway/conf.d` directory and name it `custom`:

    ```ssh
    sudo mkdir /etc/mulesoft/flex-gateway/conf.d/custom
    ```

2.  Create a YAML configuration file in the `custom` folder:

    ```ssh
    sudo touch /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Kubernetes Cluster

To configure shared storage for Flex Gateway, create a new resource using a YAML configuration file
with your storage details.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Flex Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config)

- [Declarative Configuration Reference](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide#shared-storage)

<!-- document id=5b40c502b9250bf5a1006d528bb234519a800d443fd98018a0bddfc149aaa849 url=/mulesoft/current/en-us/gateway/1.9/flex-local-shared-storage-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Shared Storage for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

Enable shared storage for distributed caching, gateway configuration caching (Connected Mode), and
rate limiting policies. Redis also provides extra memory for caching.

Production workflows should use [Redis](https://redis.io/). If Redis is not defined, shared storage
services at port 4000 are still available but use an in-memory implementation. You must configure
Redis for distributed policies to share data. All other policies use replica memory for storage.

You configure shared storage via a custom YAML file.

The following steps demonstrate Redis-based storage support for Flex Gateway running in a Docker
container, as a Linux Service, or as a Kubernetes cluster.

To configure Redis Sentinel or a TLS connection to your Redis shared storage, refer to:

- [Configure Redis Sentinel](#redis-sentinel)

- [Configure TLS for Redis-Based Shared Storage](#redis-tls)

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure Shared Storage for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure Shared Storage for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure Shared Storage for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring shared storage for Flex Gateway, complete the following tasks:

1.  [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

2.  [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

## Configure Shared Storage for Flex Gateway as a Linux Service

1.  Create a folder in the `/etc/mulesoft/flex-gateway/conf.d` directory and name it `custom`:

    ```ssh
    sudo mkdir /etc/mulesoft/flex-gateway/conf.d/custom
    ```

2.  Create a YAML configuration file in the `custom` folder:

    ```ssh
    sudo touch /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

3.  Update the file with your Redis storage configuration details. For example:

    ```ssh
    sudo vi /etc/mulesoft/flex-gateway/conf.d/custom/shared-storage-config.yaml
    ```

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Docker Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to the last step.

1.  Stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your shared storage details.

    Sample configuration for adding Redis-based shared storage:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Configuration
    metadata:
      name: shared-storage-redis
    spec:
      sharedStorage:
        redis:
          address: redis.e-commerce.svc:6379
          username: ecomm-user
          password: ecomm-pwd-123
          DB: 7
    ```

## Configure Shared Storage for Flex Gateway in a Kubernetes Cluster

To configure shared storage for Flex Gateway, create a new resource using a YAML configuration file
with your storage details.

Sample configuration for adding Redis-based shared storage:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

## Configure Redis Sentinel

Redis Sentinel provides high availability for Redis shared storage. For more information about Redis
Sentinel, refer to
[Redi Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/).

Configure Redis Sentinel using the steps described in the previous sections.

Sample configuration for adding Redis Sentinel:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage
  namespace: test-ns
spec:
  sharedStorage:
    redis:
      username: "user"
      password: "pass"
      sentinel:
        addresses:
          - internal.redis.com:6379
        masterName: "name"
        password: "pass"
      db: 0
```

## Configure TLS for Redis-Based Shared Storage

Use TLS with Redis to ensure data security between Flex Gateway and the Redis instance. Configuring
TLS enables you to protect sensitive data, prevent unauthorized access, and maintain the reliability
of your services. Additionally, configuring TLS helps organizations meet compliance requirements and
build trust with users.

TLS works with both Redis and Redis Sentinel.

Configure TLS for Redis-based shared storage using the steps described in the previous sections.

Sample configuration for adding Redis-based shared storage with TLS:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

For information about configuration parameters, see the
[Declarative Configuration Reference (Shared Storage)](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide#shared-storage).

## See Also

- [Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config)

- [Declarative Configuration Reference](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide#shared-storage)

<!-- document id=9a0656b275af821da9a9fc2797ed8c24f2da6325617f960b9be729267fc97369 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-timeout.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Timeouts in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex
  Gateway to upstream service) direction.

  By default, all Flex Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Flex
  Gateway and the upstream service can remain idle between requests.

  By default, all Flex Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Flex Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Flex
  Gateway.

  By default, all Flex Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts in Connected Mode via:

- Runtime Manager runtime configurations: Applies to all API instances in the gateway.

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Timeouts in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways**.

3.  Select your Flex Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Timeouts**.

6.  Set values for **Stream Idle Timeout**, **Upstream Connection Idle Timeout**, and **Upstream
    Response Timeout**.

7.  Apply the changes.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 300
    upstreamResponseSeconds: 15
    streamIdleSeconds: 60
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-response-timeout)

<!-- document id=c2dabac2cbc7a83fb7a7493d7104f54e91e1d5f493addac0a760ca4787f1aed3 url=/mulesoft/current/en-us/gateway/1.13/conn-timeout.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Timeouts in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni
  Gateway to upstream service) direction.

  By default, all Omni Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Omni
  Gateway and the upstream service can remain idle between requests.

  By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Omni Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Omni
  Gateway.

  By default, all Omni Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts in Connected Mode via:

- Runtime Manager runtime configurations: Applies to all API instances in the gateway.

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Timeouts in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Timeouts**.

6.  Set values for **Stream Idle Timeout**, **Upstream Connection Idle Timeout**, and **Upstream
    Response Timeout**.

7.  Apply the changes.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 300
    upstreamResponseSeconds: 15
    streamIdleSeconds: 60
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-response-timeout)

<!-- document id=62c0ec5a8e29d07620fbbbc1b7696f472330c35d2a596e1b98ff376731271e2c url=/mulesoft/current/en-us/gateway/1.9/flex-conn-timeout.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Timeouts in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex
  Gateway to upstream service) direction.

  By default, all Flex Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Flex
  Gateway and the upstream service can remain idle between requests.

  By default, all Flex Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Flex Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Flex
  Gateway.

  By default, all Flex Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts via:

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML file: Applies to all API instances and is easy to adjust.

- Policy: Applies to just one API instance or upstream providing granularity and is easy to adjust.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 300
    upstreamResponseSeconds: 15
    streamIdleSeconds: 60
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.9/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-response-timeout)

<!-- document id=60f4b765b343331793835c7a8855e1497f74515ece0ed08ed6f3819bdc158e06 url=/mulesoft/current/en-us/gateway/latest/conn-timeout.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Timeouts in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni
  Gateway to upstream service) direction.

  By default, all Omni Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Omni
  Gateway and the upstream service can remain idle between requests.

  By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Omni Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Omni
  Gateway.

  By default, all Omni Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts in Connected Mode via:

- Runtime Manager runtime configurations: Applies to all API instances in the gateway.

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set,
in this order of precedence:

1.  **Policy**: A policy applied to the API instance.

2.  **Runtime Manager runtime configuration or Configuration resource**: Used if no policy value is
    set.

3.  **Environment variable**: Used if no Runtime Manager or Configuration resource value is set.

4.  **Built-in default**: Used if none of the other values is set.

A policy value overrides the gateway-level value for the API instance it’s applied to. API instances
without the policy use the gateway-level value.

Runtime Manager runtime configurations and environment variables don’t synchronize. Changing a value
in Runtime Manager doesn’t update the corresponding `FLEX_*` environment variable on the gateway.
Because the Runtime Manager value takes precedence, the environment variable has no effect on that
setting while the Runtime Manager value is set. For how to verify the effective value, see
[Environment Variable Synchronization](https://docs.mulesoft.com/gateway/latest/conn-env-variables#environment-variable-synchronization).

## Configure Timeouts in Runtime Manager

1.  In Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways**.

3.  Select your Omni Gateway.

4.  Open **Runtime Configurations**.

5.  Open **Timeouts**.

6.  Set values for **Stream Idle Timeout**, **Upstream Connection Idle Timeout**, and **Upstream
    Response Timeout**.

7.  Apply the changes.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 60
    upstreamResponseSeconds: 15
    streamIdleSeconds: 300
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-included-response-timeout)

<!-- document id=bb1c7f737027185acf52c1e5905cf1f3af106de7975618ceeb8dfa7412e26808 url=/mulesoft/current/en-us/gateway/1.12/flex-local-timeout.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring Timeouts in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex
  Gateway to upstream service) direction.

  By default, all Flex Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Flex
  Gateway and the upstream service can remain idle between requests.

  By default, all Flex Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Flex Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Flex
  Gateway.

  By default, all Flex Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts in Local Mode via:

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 300
    upstreamResponseSeconds: 15
    streamIdleSeconds: 60
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-response-timeout)

<!-- document id=aad8d2f30f380f9d8caa9028df5e58bc4175aaeb672217470cc4703706d68b35 url=/mulesoft/current/en-us/gateway/1.13/local-timeout.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring Timeouts in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni
  Gateway to upstream service) direction.

  By default, all Omni Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Omni
  Gateway and the upstream service can remain idle between requests.

  By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Omni Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Omni
  Gateway.

  By default, all Omni Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts in Local Mode via:

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 300
    upstreamResponseSeconds: 15
    streamIdleSeconds: 60
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-response-timeout)

<!-- document id=d3b3669f3e4497d21fd81a903f2d0f8daf13dbdb06bf140b7f9b5e16c2fef515 url=/mulesoft/current/en-us/gateway/1.9/flex-local-timeout.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring Timeouts in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex
  Gateway to upstream service) direction.

  By default, all Flex Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Flex
  Gateway and the upstream service can remain idle between requests.

  By default, all Flex Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Flex Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Flex
  Gateway.

  By default, all Flex Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts via:

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML file: Applies to all API instances and is easy to adjust.

- Policy: Applies to just one API instance or upstream providing granularity and is easy to adjust.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 300
    upstreamResponseSeconds: 15
    streamIdleSeconds: 60
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/1.9/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-response-timeout)

<!-- document id=f0a9441a17c766c7a557d6c4e0c578814d731a8625b8eb449b4bd6126a7f5c6e url=/mulesoft/current/en-us/gateway/latest/local-timeout.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring Timeouts in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway offers these timeouts to improve service quality and reduce computing resource waste:

- **Stream Idle Timeout**  
  The Stream Idle Timeout enables you to set a maximum amount of a time a stream can remain idle
  without receiving any data in either the inbound (client to Omni Gateway) or outbound (Omni
  Gateway to upstream service) direction.

  By default, all Omni Gateway API instances have a stream timeout of 300 seconds.

- **Upstream Idle Timeout**  
  The Upstream Idle Timeout enables you to set a maximum amount of time a stream between Omni
  Gateway and the upstream service can remain idle between requests.

  By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds.

- **Response Timeout**  
  The Response Timeout enables you to set a maximum amount of a time Omni Gateway waits for a
  response from an upstream service. The timeout time starts at the last request sent by Omni
  Gateway.

  By default, all Omni Gateway API instances have a response timeout of 15 seconds.

You can configure these timeouts in Local Mode via:

- Environment variables: Applies to all API instances and is the most permanent configuration
  option.

- Configuration YAML resource: Applies to all API instances and is easy to adjust.

- Policy: Applies to one API instance or upstream and provides granular control.

## Configure Timeouts via Environment Variables

Configure timeouts with these environment variables:

FLEX\_STREAM\_IDLE\_TIMEOUT\_SECONDS: 300
FLEX\_UPSTREAM\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS/FLEX\_CONNECTION\_IDLE\_TIMEOUT\_SECONDS: 60
FLEX\_UPSTREAM\_RESPONSE\_TIMEOUT\_SECONDS: 15

Edit the variables with your desired configurations.

## Configure Timeouts via YAML Configuration Resources

Edit and then apply this configuration resource to update your timeouts:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: timeouts-config
spec:
  timeouts:
    upstreamConnectionIdleSeconds: 60
    upstreamResponseSeconds: 15
    streamIdleSeconds: 300
```

## Configure Timeouts via Policies

Apply these policies to your API instance or upstream service:

- [Stream Idle Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-included-stream-idle-timeout)

- [Upstream Idle Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-upstream-idle-timeout)

- [Response Timeout Policy](https://docs.mulesoft.com/gateway/latest/policies-included-response-timeout)

<!-- document id=007bf1c223c8bc3e8132163dad3c9a4e0d423c976aeb6e923ccb53b03f365b1f url=/mulesoft/current/en-us/gateway/1.12/flex-conn-tls-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring TLS Context for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. After you
[create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can add a TLS
context or a mutual authentication TLS (mTLS) context and apply the TLS context to API instances in
API Manager to encrypt their inbound and outbound traffic.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Flex Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

Flex Gateway implements inbound TLS at the port level, meaning that an inbound TLS context applied
to an API instance is also applied to all other instances that share the same port. To learn more
about how TLS context is shared across ports, see
[Inbound TLS Context Applied to Shared Ports](#tls-context-applied-to-shared-ports).

Port sharing is not a concern for outbound TLS. You can select the outbound TLS context for each
individual upstream service.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the TLS context for a Flex Gateway Connected Mode, complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

- Ensure the following permissions are enabled:

  - _Grant access to secrets_ in Secrets Manager

  - _Deploy API Proxies_ in API Manager

    Your Anypoint Platform Admin can add these permissions in Access Management. See
    [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for
    more information.

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## TLS Configuration Options

You can configure your TLS context to support regular TLS and mTLS in both the inbound and outbound
direction. Depending on the desired configuration, you must add different certificate files to your
secret group and select different TLS context configuration options.

Refer to the following cross reference table for the required TLS context configuration settings you
need in the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Inbound TLS</th><th>Inbound mTLS</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Selected</p></div></div></td><td><div><div><p>Selected</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, you can create different TLS contexts for the different traffic
directions of your API instance. However, you can also use the same TLS context to support different
traffic directions, but you cannot support TLS and mTLS for the same direction using the same
context. If you use the same TLS context for different directions, ensure you include the required
parameters for both directions.

## Add a TLS Context for Flex Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and a keystore
or truststore. Optionally, you can add context expiration date and ALPN Protocols and configure the
inbound and outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy the API instance to apply the changes. You must individually
> redeploy all instances affected by the change. To redeploy API instances, see
> [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  Ensure your secret group is downloadable. This enables you to apply your TLS context to API
    instances.

    To ensure your secret group is downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**

    3.  If **Secret Group Downloadable** is not selected, select it, then click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Flex Gateway** to use the TLS context as the SSL validation for Flex Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      You can choose to support a range of TLS versions or a single version by selecting the same
      version for both the minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, from the drop-down list, select the keystore to store in
      the TLS context. Only PEM type keystores are visible. The keystore contains the certificate
      Flex Gateway presents to the remote party for both inbound and outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, from the drop-down list, select a truststore to store
      certificates trusted by the client. Only PEM type truststores are visible. The truststore
      contains the CA path that Flex uses to validate the remote party certificate for both inbound
      and outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Flex Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Inbound Settings**  
      If you want to support mTLS for inbound traffic, select **Validate Client certificate**.

    - **Outbound Settings**  
      If you do not want support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an API instance either when creating a new instance or by editing an
existing instance.

API instance settings configuration has two parts, the downstream configuration and the upstream
configuration. Inbound TLS context is a downstream configuration option, and outbound TLS context is
an upstream configuration option. When adding a new API instance, the downstream and upstream
configuration is on separate pages. When editing an API instance, the downstream and upstream
configuration options appear on the same page but are in different sections.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Upstream or downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Select **HTTPS** for the **Protocol** configuration field if configuring an inbound TLS context.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Inbound TLS Context Applied to Shared Ports

Though a port must have an API instance to have an inbound TLS context applied, the inbound TLS
context is applied to the port rather than the API instance.

Applying an inbound TLS context to an API instance that shares its port with other instances applies
the inbound TLS context to all instances sharing the port.

When you apply, edit, or remove the inbound TLS context of an API instance sharing a port, API
Manager shows a warning with a list of the instances sharing the port. You can then choose to
override the inbound TLS context of the listed API instances. Overriding the inbound TLS context of
the API instances that share the port applies the inbound TLS context to the instances and then
redeploys the instances.

Overriding the inbound TLS context of deployed API instances redeploys the instances. Redeploying
causes a brief period of downtime in the API instances.

If you edit the port of an API instance that previously shared a port and an inbound TLS context
with other instances, the inbound TLS context remains applied to the instances on the previous port.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config)

- [Transport Layer Security Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

<!-- document id=17c5536b45584eb97a8bd8eb320f29d963b031e925eecefae5cf1c17394cd6dd url=/mulesoft/current/en-us/gateway/1.9/flex-conn-tls-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring TLS Context for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. After you
[create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can add a TLS
context or a mutual authentication TLS (mTLS) context and apply the TLS context to API instances in
API Manager to encrypt their inbound and outbound traffic.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Flex Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

Flex Gateway implements inbound TLS at the port level, meaning that an inbound TLS context applied
to an API instance is also applied to all other instances that share the same port. To learn more
about how TLS context is shared across ports, see
[Inbound TLS Context Applied to Shared Ports](#tls-context-applied-to-shared-ports).

Port sharing is not a concern for outbound TLS. You can select the outbound TLS context for each
individual upstream service.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the TLS context for a Flex Gateway Connected Mode, complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

- Ensure the following permissions are enabled:

  - _Grant access to secrets_ in Secrets Manager

  - _Deploy API Proxies_ in API Manager

    Your Anypoint Platform Admin can add these permissions in Access Management. See
    [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for
    more information.

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## TLS Configuration Options

You can configure your TLS context to support regular TLS and mTLS in both the inbound and outbound
direction. Depending on the desired configuration, you must add different certificate files to your
secret group and select different TLS context configuration options.

Refer to the following cross reference table for the required TLS context configuration settings you
need in the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Inbound TLS</th><th>Inbound mTLS</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Selected</p></div></div></td><td><div><div><p>Selected</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, you can create different TLS contexts for the different traffic
directions of your API instance. However, you can also use the same TLS context to support different
traffic directions, but you cannot support TLS and mTLS for the same direction using the same
context. If you use the same TLS context for different directions, ensure you include the required
parameters for both directions.

## Add a TLS Context for Flex Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and a keystore
or truststore. Optionally, you can add context expiration date and ALPN Protocols and configure the
inbound and outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy the API instance to apply the changes. You must individually
> redeploy all instances affected by the change. To redeploy API instances, see
> [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  Ensure your secret group is downloadable. This enables you to apply your TLS context to API
    instances.

    To ensure your secret group is downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**

    3.  If **Secret Group Downloadable** is not selected, select it, then click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Flex Gateway** to use the TLS context as the SSL validation for Flex Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      You can choose to support a range of TLS versions or a single version by selecting the same
      version for both the minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, from the drop-down list, select the keystore to store in
      the TLS context. Only PEM type keystores are visible. The keystore contains the certificate
      Flex Gateway presents to the remote party for both inbound and outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, from the drop-down list, select a truststore to store
      certificates trusted by the client. Only PEM type truststores are visible. The truststore
      contains the CA path that Flex uses to validate the remote party certificate for both inbound
      and outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Flex Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Inbound Settings**  
      If you want to support mTLS for inbound traffic, select **Validate Client certificate**.

    - **Outbound Settings**  
      If you do not want support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an API instance either when creating a new instance or by editing an
existing instance.

API instance settings configuration has two parts, the downstream configuration and the upstream
configuration. Inbound TLS context is a downstream configuration option, and outbound TLS context is
an upstream configuration option. When adding a new API instance, the downstream and upstream
configuration is on separate pages. When editing an API instance, the downstream and upstream
configuration options appear on the same page but are in different sections.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Upstream or downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Select **HTTPS** for the **Protocol** configuration field if configuring an inbound TLS context.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Inbound TLS Context Applied to Shared Ports

Though a port must have an API instance to have an inbound TLS context applied, the inbound TLS
context is applied to the port rather than the API instance.

Applying an inbound TLS context to an API instance that shares its port with other instances applies
the inbound TLS context to all instances sharing the port.

When you apply, edit, or remove the inbound TLS context of an API instance sharing a port, API
Manager shows a warning with a list of the instances sharing the port. You can then choose to
override the inbound TLS context of the listed API instances. Overriding the inbound TLS context of
the API instances that share the port applies the inbound TLS context to the instances and then
redeploys the instances.

Overriding the inbound TLS context of deployed API instances redeploys the instances. Redeploying
causes a brief period of downtime in the API instances.

If you edit the port of an API instance that previously shared a port and an inbound TLS context
with other instances, the inbound TLS context remains applied to the instances on the previous port.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config)

- [Transport Layer Security Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

<!-- document id=1cb72f7a2cb582b77e2552b3596f68942cbae56cc1baf3d07795034631494211 url=/mulesoft/current/en-us/gateway/1.12/flex-local-tls-config.md -->

---
product: Omni Gateway
version: 1.12
---

# Configuring TLS Context for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. To use TLS when creating an API instance using Flex Gateway in
Local Mode as your runtime, you must configure the TLS context in a `PolicyBinding` YAML
configuration file.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Flex Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

The following tutorials demonstrate how to apply a configured `PolicyBinding` resource. For how to
configure the resource, see the policy configuration pages:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

For inbound TLS, you bind the policy resource to the API instance. For outbound TLS, you bind the
policy resource to the upstream service.

You can configure the TLS context for a Flex Gateway running in a Docker container, as a Linux
Service, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure TLS Context for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure TLS Context for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure TLS Context for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring the TLS context for a Flex Gateway, you must complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

## Configure TLS Context for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

2.  Update the file with your TLS context configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

3.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Flex Gateway in a Docker Container

> [!NOTE] If you have already added volume for a folder with your Flex Gateway configuration files,
> skip to the last step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your TLS context details.

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

5.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Flex Gateway in a Kubernetes Cluster

To configure the TLS context for Flex Gateway, create a new resource using a YAML configuration file
with your TLS context details.

The following configuration file only applies inbound TLS to one API instance. For all configuration
file options, such as mTLS and outbound TLS, see:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

  **Sample configuration for adding inbound TLS context for a specific API instance:**

  ```yaml
  apiVersion: gateway.mulesoft.com/v1alpha1
  kind: PolicyBinding
  metadata:
    name: ingress-https-tls
  spec:
    targetRef:
      kind: ApiInstance
      name: ingress-https
    policyRef:
      name: tls
    config:
      certificate:
        key: |
          # -----BEGIN PRIVATE KEY-----
          # insert certificate key
          # -----END PRIVATE KEY-----
        crt: |
          # -----BEGIN CERTIFICATE-----
          # insert certificate
          # -----END CERTIFICATE-----
      alpn:
        - http/1.1
        - h2
      minversion: "1.1"
      maxversion: "1.3"
      ciphers:
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
        - TLS_RSA_WITH_AES_128_GCM_SHA256
        - TLS_RSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
        - TLS_RSA_WITH_AES_256_GCM_SHA384
        - TLS_RSA_WITH_AES_256_CBC_SHA
  ```

  > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

<!-- document id=7348ceb91fa5fe104c18160987600a05a9ba78cdecb34bca28cc999f76d7821c url=/mulesoft/current/en-us/gateway/1.9/flex-local-tls-config.md -->

---
product: Omni Gateway
version: 1.9
---

# Configuring TLS Context for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. To use TLS when creating an API instance using Flex Gateway in
Local Mode as your runtime, you must configure the TLS context in a `PolicyBinding` YAML
configuration file.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Flex Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

The following tutorials demonstrate how to apply a configured `PolicyBinding` resource. For how to
configure the resource, see the policy configuration pages:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound)

For inbound TLS, you bind the policy resource to the API instance. For outbound TLS, you bind the
policy resource to the upstream service.

You can configure the TLS context for a Flex Gateway running in a Docker container, as a Linux
Service, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure TLS Context for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure TLS Context for Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure TLS Context for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring the TLS context for a Flex Gateway, you must complete the following tasks:

- [Download Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- [Register and Run Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

## Configure TLS Context for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in the Flex Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

2.  Update the file with your TLS context configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

3.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Flex Gateway in a Docker Container

> [!NOTE] If you have already added volume for a folder with your Flex Gateway configuration files,
> skip to the last step.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Restart your Flex Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your TLS context details.

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

5.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Flex Gateway in a Kubernetes Cluster

To configure the TLS context for Flex Gateway, create a new resource using a YAML configuration file
with your TLS context details.

The following configuration file only applies inbound TLS to one API instance. For all configuration
file options, such as mTLS and outbound TLS, see:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound)

  **Sample configuration for adding inbound TLS context for a specific API instance:**

  ```yaml
  apiVersion: gateway.mulesoft.com/v1alpha1
  kind: PolicyBinding
  metadata:
    name: ingress-https-tls
  spec:
    targetRef:
      kind: ApiInstance
      name: ingress-https
    policyRef:
      name: tls
    config:
      certificate:
        key: |
          # -----BEGIN PRIVATE KEY-----
          # insert certificate key
          # -----END PRIVATE KEY-----
        crt: |
          # -----BEGIN CERTIFICATE-----
          # insert certificate
          # -----END CERTIFICATE-----
      alpn:
        - http/1.1
        - h2
      minversion: "1.1"
      maxversion: "1.3"
      ciphers:
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
        - TLS_RSA_WITH_AES_128_GCM_SHA256
        - TLS_RSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
        - TLS_RSA_WITH_AES_256_GCM_SHA384
        - TLS_RSA_WITH_AES_256_CBC_SHA
  ```

  > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound)

<!-- document id=a3dee2d8dc6713993e33c96384ad69aeea79b586c102441b7cf03d2c9fdd43dc url=/mulesoft/current/en-us/gateway/1.13/conn-tls-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring TLS Context for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. After you
[create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can add a TLS
context or a mutual authentication TLS (mTLS) context and apply the TLS context to API instances in
API Manager to encrypt their inbound and outbound traffic.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Omni Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

Omni Gateway implements inbound TLS at the port level, meaning that an inbound TLS context applied
to an API instance is also applied to all other instances that share the same port. To learn more
about how TLS context is shared across ports, see
[Inbound TLS Context Applied to Shared Ports](#tls-context-applied-to-shared-ports).

Port sharing is not a concern for outbound TLS. You can select the outbound TLS context for each
individual upstream service.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the TLS context for an Omni Gateway Connected Mode, complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

- Ensure the following permissions are enabled:

  - _Grant access to secrets_ in Secrets Manager

  - _Deploy API Proxies_ in API Manager

    Your Anypoint Platform Admin can add these permissions in Access Management. See
    [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for
    more information.

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## TLS Configuration Options

You can configure your TLS context to support regular TLS and mTLS in both the inbound and outbound
direction. Depending on the desired configuration, you must add different certificate files to your
secret group and select different TLS context configuration options.

Refer to the following cross reference table for the required TLS context configuration settings you
need in the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Inbound TLS</th><th>Inbound mTLS</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Selected</p></div></div></td><td><div><div><p>Selected</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, you can create different TLS contexts for the different traffic
directions of your API instance. However, you can also use the same TLS context to support different
traffic directions, but you cannot support TLS and mTLS for the same direction using the same
context. If you use the same TLS context for different directions, ensure you include the required
parameters for both directions.

## Add a TLS Context for Omni Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and a keystore
or truststore. Optionally, you can add context expiration date and ALPN Protocols and configure the
inbound and outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy the API instance to apply the changes. You must individually
> redeploy all instances affected by the change. To redeploy API instances, see
> [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  Ensure your secret group is downloadable. This enables you to apply your TLS context to API
    instances.

    To ensure your secret group is downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**

    3.  If **Secret Group Downloadable** is not selected, select it, then click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Omni Gateway** to use the TLS context as the SSL validation for Omni Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      You can choose to support a range of TLS versions or a single version by selecting the same
      version for both the minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, from the drop-down list, select the keystore to store in
      the TLS context. Only PEM type keystores are visible. The keystore contains the certificate
      Omni Gateway presents to the remote party for both inbound and outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, from the drop-down list, select a truststore to store
      certificates trusted by the client. Only PEM type truststores are visible. The truststore
      contains the CA path that Omni uses to validate the remote party certificate for both inbound
      and outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Omni Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Inbound Settings**  
      If you want to support mTLS for inbound traffic, select **Validate Client certificate**.

    - **Outbound Settings**  
      If you do not want support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an API instance either when creating a new instance or by editing an
existing instance.

API instance settings configuration has two parts, the downstream configuration and the upstream
configuration. Inbound TLS context is a downstream configuration option, and outbound TLS context is
an upstream configuration option. When adding a new API instance, the downstream and upstream
configuration is on separate pages. When editing an API instance, the downstream and upstream
configuration options appear on the same page but are in different sections.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Upstream or downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Select **HTTPS** for the **Protocol** configuration field if configuring an inbound TLS context.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Inbound TLS Context Applied to Shared Ports

Though a port must have an API instance to have an inbound TLS context applied, the inbound TLS
context is applied to the port rather than the API instance.

Applying an inbound TLS context to an API instance that shares its port with other instances applies
the inbound TLS context to all instances sharing the port.

When you apply, edit, or remove the inbound TLS context of an API instance sharing a port, API
Manager shows a warning with a list of the instances sharing the port. You can then choose to
override the inbound TLS context of the listed API instances. Overriding the inbound TLS context of
the API instances that share the port applies the inbound TLS context to the instances and then
redeploys the instances.

Overriding the inbound TLS context of deployed API instances redeploys the instances. Redeploying
causes a brief period of downtime in the API instances.

If you edit the port of an API instance that previously shared a port and an inbound TLS context
with other instances, the inbound TLS context remains applied to the instances on the previous port.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config)

- [Transport Layer Security Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

<!-- document id=a927bd8ed12b25b2cf7b0e95bb489f3522743bd1a46153a698268af22969a20a url=/mulesoft/current/en-us/gateway/latest/conn-tls-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring TLS Context for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. After you
[create a secret group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task), you can add a TLS
context or a mutual authentication TLS (mTLS) context and apply the TLS context to API instances in
API Manager to encrypt their inbound and outbound traffic.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Omni Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

Omni Gateway implements inbound TLS at the port level, meaning that an inbound TLS context applied
to an API instance is also applied to all other instances that share the same port. To learn more
about how TLS context is shared across ports, see
[Inbound TLS Context Applied to Shared Ports](#tls-context-applied-to-shared-ports).

Port sharing is not a concern for outbound TLS. You can select the outbound TLS context for each
individual upstream service.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Before You Begin

Before configuring the TLS context for an Omni Gateway Connected Mode, complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

- Ensure the following permissions are enabled:

  - _Grant access to secrets_ in Secrets Manager

  - _Deploy API Proxies_ in API Manager

    Your Anypoint Platform Admin can add these permissions in Access Management. See
    [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for
    more information.

- [Create a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task)

  When adding a secret group, refer to the [TLS Configuration Options](#tls-configuration-options).

  Depending on your desired configuration, either:

  - [Add a Keystore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-keystore)

  - [Add a Trustore](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#adding-a-truststore)

    > [!NOTE] Privacy Enhanced Mail (PEM) type is required for your Keystore or Truststore.

## TLS Configuration Options

You can configure your TLS context to support regular TLS and mTLS in both the inbound and outbound
direction. Depending on the desired configuration, you must add different certificate files to your
secret group and select different TLS context configuration options.

Refer to the following cross reference table for the required TLS context configuration settings you
need in the [Add a TLS Context](#add-a-tls-context) step:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Inbound TLS</th><th>Inbound mTLS</th><th>Outbound TLS</th><th>Outbound mTLS</th></tr></thead><tbody><tr><td><div><div><p><strong>Keystore</strong></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td></tr><tr><td><div><div><p><strong>Truststore</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Required, unless skip server cert validation is selected</p></div></div></td><td><div><div><p>Required to validate upstream certificate</p></div></div></td></tr><tr><td><div><div><p><strong>Validate Client certificate</strong></p></div></div></td><td><div><div><p>Not Selected</p></div></div></td><td><div><div><p>Selected</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td></tr><tr><td><div><div><p><strong>Skip server certificate validation</strong></p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Not Used</p></div></div></td><td><div><div><p>Either</p></div></div></td><td><div><div><p>Not Selected</p></div></div></td></tr></tbody></table>

A parameter that is "Not Used" for a configuration implies its status does not affect configuration.

To simplify your configurations, you can create different TLS contexts for the different traffic
directions of your API instance. However, you can also use the same TLS context to support different
traffic directions, but you cannot support TLS and mTLS for the same direction using the same
context. If you use the same TLS context for different directions, ensure you include the required
parameters for both directions.

## Add a TLS Context for Omni Gateway

Adding a TLS context to your secret group requires supplying a name, target, version, and a keystore
or truststore. Optionally, you can add context expiration date and ALPN Protocols and configure the
inbound and outbound settings.

> [!WARNING] If you edit a secret group, including a TLS context, that is currently applied to an
> API instance, you must redeploy the API instance to apply the changes. You must individually
> redeploy all instances affected by the change. To redeploy API instances, see
> [Redeploy an API Instance](#redeploy-api-instance).

To add a TLS context:

1.  Go to **Anypoint Platform > Secrets Manager**.

2.  Ensure your secret group is downloadable. This enables you to apply your TLS context to API
    instances.

    To ensure your secret group is downloadable:

    1.  Click the pencil icon next to the name of your secret group.

    2.  If **Secret Group Downloadable** is selected, click **Cancel**

    3.  If **Secret Group Downloadable** is not selected, select it, then click **Save**.

3.  In the **Secret Groups** list view, click the **Edit** button of the secret group to add a TLS
    context.

4.  Select **TLS Context** in the menu on the left, and click **Add TLS Context**.

5.  In the Create TLS context screen, add the required information:

    - **Name**  
      Enter a name for your TLS context.

    - **Target**  
      Select **Omni Gateway** to use the TLS context as the SSL validation for Omni Gateway APIs.

    - **Min TLS Version** and **Max TLS Version**  
      You can choose to support a range of TLS versions or a single version by selecting the same
      version for both the minimum and maximum.

    - **Keystore**  
      If necessary for your configuration, from the drop-down list, select the keystore to store in
      the TLS context. Only PEM type keystores are visible. The keystore contains the certificate
      Omni Gateway presents to the remote party for both inbound and outbound TLS.

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

    - **Truststore**  
      If necessary for your configuration, from the drop-down list, select a truststore to store
      certificates trusted by the client. Only PEM type truststores are visible. The truststore
      contains the CA path that Omni uses to validate the remote party certificate for both inbound
      and outbound TLS.

      > [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
      > Common Name (CN) field is deprecated.
      >
      > Omni Gateway supports the SAN extension of type `dNSName`.

    - **Expiration Date**  
      Optionally, enter an expiration date for the TLS context.

    - **ALPN Protocols**  
      By default, **H2 - HTTP/1.1** are the selected ALPN protocols. Change this value to support
      different protocols.

    - **Inbound Settings**  
      If you want to support mTLS for inbound traffic, select **Validate Client certificate**.

    - **Outbound Settings**  
      If you do not want support mTLS for outbound traffic, select **Skip server certificate
      validation**.

6.  If you want to customize cipher support for your TLS context, [Select Ciphers](#select-ciphers).

    Cipher selection is not available if only supporting TLS version 1.3.

7.  Click **Save**.

## Apply a TLS Context to an API

You can apply a TLS context to an API instance either when creating a new instance or by editing an
existing instance.

API instance settings configuration has two parts, the downstream configuration and the upstream
configuration. Inbound TLS context is a downstream configuration option, and outbound TLS context is
an upstream configuration option. When adding a new API instance, the downstream and upstream
configuration is on separate pages. When editing an API instance, the downstream and upstream
configuration options appear on the same page but are in different sections.

For information about either option, see the relevant tutorial:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Editing an API Instance](https://docs.mulesoft.com/api-manager/latest/edit-api-endpoint-task)

To apply a TLS context:

1.  Go to **Anypoint Platform > API Manager**.

2.  Navigate to either the:

    - Upstream or downstream configuration page, if adding a new API instance.

    - **Settings** page, if editing an existing API instance.

3.  Select **HTTPS** for the **Protocol** configuration field if configuring an inbound TLS context.

4.  Click **Add TLS Context**.

    1.  Select a **Secret Group**.

    2.  Select a **TLS Context**.

    3.  Click **Ok**.

5.  Finish creating the API instance or save the configuration edits.

## Inbound TLS Context Applied to Shared Ports

Though a port must have an API instance to have an inbound TLS context applied, the inbound TLS
context is applied to the port rather than the API instance.

Applying an inbound TLS context to an API instance that shares its port with other instances applies
the inbound TLS context to all instances sharing the port.

When you apply, edit, or remove the inbound TLS context of an API instance sharing a port, API
Manager shows a warning with a list of the instances sharing the port. You can then choose to
override the inbound TLS context of the listed API instances. Overriding the inbound TLS context of
the API instances that share the port applies the inbound TLS context to the instances and then
redeploys the instances.

Overriding the inbound TLS context of deployed API instances redeploys the instances. Redeploying
causes a brief period of downtime in the API instances.

If you edit the port of an API instance that previously shared a port and an inbound TLS context
with other instances, the inbound TLS context remains applied to the instances on the previous port.

## Edit Secret Groups and Redeploy API Instances

To edit a secret group, see
[Edit a Secret Group](https://docs.mulesoft.com/anypoint-security/asm-secret-group-creation-task#edit-a-secret-group).

If you edit a secret group currently applied to an API instance, to apply the changes to the API
instance, you must individually redeploy all instances the changes affect.

To redeploy an API instance:

1.  Go to **Anypoint Platform > API Manager**.

2.  Click the name of the API instance to redeploy.

3.  Click **Runtime & Endpoint Configuration > Save & Apply**.

## Select Ciphers

When you configure a TLS context, Secrets Manager applies default ciphers based on the TLS versions
you select. In addition to the defaults, you can select other ciphers to use with the selected TLS
version. Each TLS context can have multiple ciphers.

To select ciphers:

1.  Click **Ciphers** to see available ciphers.

2.  Select ciphers.

    Cipher selection is not available if only supporting TLS version 1.3.

3.  Click **Save**

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, you must support the TLS
1.3 default ciphers.

If you support TLS 1.2, the TLS 1.2 default Ciphers are selected. However, unlike TLS 1.3, you can
customize different TLS 1.2 ciphers.

> [!IMPORTANT] For outbound TLS Context, ensure that your API upstream supports the selected ciphers
> and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 GCM SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 GCM SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE ECDSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE RSA WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 128 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS ECDHE PSK WITH AES 256 CBC SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tls-config)

- [Transport Layer Security Policy](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

<!-- document id=5f1eb73dadf4ea197e4722e07f960afe1bd8ffe14afa0d4159cb94f9c95b7f33 url=/mulesoft/current/en-us/gateway/1.13/local-tls-config.md -->

---
product: Omni Gateway
version: 1.13
---

# Configuring TLS Context for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. To use TLS when creating an API instance using Omni Gateway in
Local Mode as your runtime, you must configure the TLS context in a `PolicyBinding` YAML
configuration file.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Omni Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

The following tutorials demonstrate how to apply a configured `PolicyBinding` resource. For how to
configure the resource, see the policy configuration pages:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound)

For inbound TLS, you bind the policy resource to the API instance. For outbound TLS, you bind the
policy resource to the upstream service.

You can configure the TLS context for an Omni Gateway running in a Docker container, as a Linux
Service, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure TLS Context for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure TLS Context for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure TLS Context for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring the TLS context for an Omni Gateway, you must complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

## Configure TLS Context for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

2.  Update the file with your TLS context configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

3.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Omni Gateway in a Docker Container

> [!NOTE] If you have already added volume for a folder with your Omni Gateway configuration files,
> skip to the last step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your TLS context details.

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

5.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Omni Gateway in a Kubernetes Cluster

To configure the TLS context for Omni Gateway, create a new resource using a YAML configuration file
with your TLS context details.

The following configuration file only applies inbound TLS to one API instance. For all configuration
file options, such as mTLS and outbound TLS, see:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound)

  **Sample configuration for adding inbound TLS context for a specific API instance:**

  ```yaml
  apiVersion: gateway.mulesoft.com/v1alpha1
  kind: PolicyBinding
  metadata:
    name: ingress-https-tls
  spec:
    targetRef:
      kind: ApiInstance
      name: ingress-https
    policyRef:
      name: tls
    config:
      certificate:
        key: |
          # -----BEGIN PRIVATE KEY-----
          # insert certificate key
          # -----END PRIVATE KEY-----
        crt: |
          # -----BEGIN CERTIFICATE-----
          # insert certificate
          # -----END CERTIFICATE-----
      alpn:
        - http/1.1
        - h2
      minversion: "1.1"
      maxversion: "1.3"
      ciphers:
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
        - TLS_RSA_WITH_AES_128_GCM_SHA256
        - TLS_RSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
        - TLS_RSA_WITH_AES_256_GCM_SHA384
        - TLS_RSA_WITH_AES_256_CBC_SHA
  ```

  > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound)

<!-- document id=f90274d7987def883ec4478b0a16a05e7e6ba024005410a4414ee339af13b23c url=/mulesoft/current/en-us/gateway/latest/local-tls-config.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Configuring TLS Context for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API
instances, and upstream services. To use TLS when creating an API instance using Omni Gateway in
Local Mode as your runtime, you must configure the TLS context in a `PolicyBinding` YAML
configuration file.

When you add a TLS context, you can also select the ciphers to use with the TLS context and
configure different inbound and outbound validation settings.

Omni Gateway supports the following:

- Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS

- Regular TLS between an API instance and an upstream service, referred to as outbound TLS

- Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

The following tutorials demonstrate how to apply a configured `PolicyBinding` resource. For how to
configure the resource, see the policy configuration pages:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound)

For inbound TLS, you bind the policy resource to the API instance. For outbound TLS, you bind the
policy resource to the upstream service.

You can configure the TLS context for an Omni Gateway running in a Docker container, as a Linux
Service, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Configure TLS Context for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Configure TLS Context for Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Configure TLS Context for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring the TLS context for an Omni Gateway, you must complete the following tasks:

- [Download Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- [Register and Run Omni Gateway](https://docs.mulesoft.com/gateway/latest/local-reg-run)

## Configure TLS Context for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in the Omni Gateway configuration directory:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

2.  Update the file with your TLS context configuration details. For example:

    ```ssh
    sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
    ```

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

3.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Omni Gateway in a Docker Container

> [!NOTE] If you have already added volume for a folder with your Omni Gateway configuration files,
> skip to the last step.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Restart your Omni Gateway with an additional volume for the new `app` directory:

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

4.  Create and save a YAML configuration file in your `app` folder with your TLS context details.

    The following configuration file only applies inbound TLS to one API instance. For all
    configuration file options, such as mTLS and outbound TLS, see:

    - [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

    - [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound)

      **Sample configuration for adding inbound TLS context for a specific API instance:**

      ```yaml
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: PolicyBinding
      metadata:
        name: ingress-https-tls
      spec:
        targetRef:
          kind: ApiInstance
          name: ingress-https
        policyRef:
          name: tls
        config:
          certificate:
            key: |
              # -----BEGIN PRIVATE KEY-----
              # insert certificate key
              # -----END PRIVATE KEY-----
            crt: |
              # -----BEGIN CERTIFICATE-----
              # insert certificate
              # -----END CERTIFICATE-----
          alpn:
            - http/1.1
            - h2
          minversion: "1.1"
          maxversion: "1.3"
          ciphers:
            - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
            - TLS_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
            - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
            - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
            - TLS_RSA_WITH_AES_128_GCM_SHA256
            - TLS_RSA_WITH_AES_128_CBC_SHA
            - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
            - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
            - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
            - TLS_RSA_WITH_AES_256_GCM_SHA384
            - TLS_RSA_WITH_AES_256_CBC_SHA
      ```

      > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

5.  Verify that the policy was correctly applied.

    The following example `curl` command tests an HTTPS endpoint with a certificate that matches the
    certificate specified in the policy binding configuration resource.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v
    ```

    The command should return information on the TLS handshake, as well as an HTTP status of `200`
    for the endpoint:

    \* TLSv1.3 (OUT), TLS handshake, Client hello (1): \* TLSv1.3 (IN), TLS handshake, Server hello
    (2): \* TLSv1.2 (IN), TLS handshake, Certificate (11): \* TLSv1.2 (IN), TLS handshake, Server
    key exchange (12): \* TLSv1.2 (IN), TLS handshake, Server finished (14): \* TLSv1.2 (OUT), TLS
    handshake, Client key exchange (16): \* TLSv1.2 (OUT), TLS change cipher, Client hello (1): \*
    TLSv1.2 (OUT), TLS handshake, Finished (20): \* SSL connection using TLSv1.2 /
    ECDHE-RSA-CHACHA20-POLY1305 \* ALPN, server did not agree to a protocol ...

    > HTTP/1.1 200 OK

    For inbound mTLS, the following example `curl` command requests an API proxy whose basepath is
    `/`.

    ```ssh
    curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
    --cert <CLIENTAPP_CERT_FILE> \
    --key <CLIENTAPP_KEY_FILE> \
    --cacert <SERVER_CERT_FILE> \
    --resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v
    ```

    > [!NOTE] The configuration `key` and `crt` values must be correctly indented, otherwise `curl`
    > returns the following error when attempting to test the endpoint:
    >
    > curl: (35) error:1408F10B:SSL routines:ssl3\_get\_record:wrong version number

## Configure TLS Context for Omni Gateway in a Kubernetes Cluster

To configure the TLS context for Omni Gateway, create a new resource using a YAML configuration file
with your TLS context details.

The following configuration file only applies inbound TLS to one API instance. For all configuration
file options, such as mTLS and outbound TLS, see:

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound)

  **Sample configuration for adding inbound TLS context for a specific API instance:**

  ```yaml
  apiVersion: gateway.mulesoft.com/v1alpha1
  kind: PolicyBinding
  metadata:
    name: ingress-https-tls
  spec:
    targetRef:
      kind: ApiInstance
      name: ingress-https
    policyRef:
      name: tls
    config:
      certificate:
        key: |
          # -----BEGIN PRIVATE KEY-----
          # insert certificate key
          # -----END PRIVATE KEY-----
        crt: |
          # -----BEGIN CERTIFICATE-----
          # insert certificate
          # -----END CERTIFICATE-----
      alpn:
        - http/1.1
        - h2
      minversion: "1.1"
      maxversion: "1.3"
      ciphers:
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
        - TLS_RSA_WITH_AES_128_GCM_SHA256
        - TLS_RSA_WITH_AES_128_CBC_SHA
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
        - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
        - TLS_RSA_WITH_AES_256_GCM_SHA384
        - TLS_RSA_WITH_AES_256_CBC_SHA
  ```

  > [!NOTE] To comply with security standards, all certificates must be 2048 bits or longer.

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound)

<!-- document id=256cb1ca5c38c475b3bb9c17e423fe5a6d07feac43c8bb8e5af06755190affce url=/mulesoft/current/en-us/gateway/1.12/policies-tls-configuration.md -->

---
product: Omni Gateway
version: 1.12
keywords: policy, custom
---

# Configuring TLS for Outgoing Policy Requests

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Some Flex Gateway policies make outgoing requests to HTTP and gRPC upstream services. For example,
the [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-oauth-token-introspection) sends token
validation requests to an OAuth 2.0 service, and the
[External Authorization Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-external-authorization) forwards incoming client
requests to an authorization service.

By default, Managed and Self-Managed Flex Gateways protect these connections with a default TLS
Context. The default TLS context is not mTLS and uses the default ciphers listed in
[TLS Cipher Support on Flex Gateway](#local-support).

To override the default TLS context, configure a custom default TLS context for all outgoing
requests from policies. You can’t configure a custom default TLS context for Managed Flex Gateway.

## Configure a TLS Context for Self-Managed Gateways

For both local and connected mode, use a YAML configuration file to configure TLS between a policy
and an upstream service:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: default-tls spec:
defaultTLS: outboundPolicyCalls: skipValidation: <boolean> // OPTIONAL trustedCA: <string> #
OPTIONAL, defaults to the CA of operating systems certificate: // OPTIONAL key: <string> // OPTIONAL
crt: <string> // OPTIONAL alpn: <array> // OPTIONAL minversion: <string> // OPTIONAL maxversion:
<string> // OPTIONAL ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, ensure that your API upstream supports the listed ciphers.
For the supported ciphers, see [TLS Cipher Support on Flex Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the upstream certificate is not validated.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the upstream server certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate to present for mTLS. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Flex Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

<!-- document id=46d87a2b0260ea5c07e23256902b64ba88b0ee9cafe46cb0c7cfe03874d2bb78 url=/mulesoft/current/en-us/gateway/1.13/policies-tls-configuration.md -->

---
product: Omni Gateway
version: 1.13
keywords: policy, custom
---

# Configuring TLS for Outgoing Policy Requests

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Some Omni Gateway policies make outgoing requests to HTTP and gRPC upstream services. For example,
the [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-oauth-token-introspection) sends token
validation requests to an OAuth 2.0 service, and the
[External Authorization Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-external-authorization) forwards incoming client
requests to an authorization service.

By default, Managed and Self-Managed Omni Gateways protect these connections with a default TLS
Context. The default TLS context is not mTLS and uses the default ciphers listed in
[TLS Cipher Support on Omni Gateway](#local-support).

To override the default TLS context, configure a custom default TLS context for all outgoing
requests from policies. You can’t configure a custom default TLS context for Managed Omni Gateway.

## Configure a TLS Context for Self-Managed Gateways

For both local and connected mode, use a YAML configuration file to configure TLS between a policy
and an upstream service:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: default-tls spec:
defaultTLS: outboundPolicyCalls: skipValidation: <boolean> // OPTIONAL trustedCA: <string> #
OPTIONAL, defaults to the CA of operating systems certificate: // OPTIONAL key: <string> // OPTIONAL
crt: <string> // OPTIONAL alpn: <array> // OPTIONAL minversion: <string> // OPTIONAL maxversion:
<string> // OPTIONAL ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, ensure that your API upstream supports the listed ciphers.
For the supported ciphers, see [TLS Cipher Support on Omni Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the upstream certificate is not validated.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the upstream server certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate to present for mTLS. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

<!-- document id=1aa049da09b42d683c265f7557ad11d4a8dff482b785a3ad5f222b6f8af000cb url=/mulesoft/current/en-us/gateway/latest/policies-tls-configuration.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: policy, custom
---

# Configuring TLS for Outgoing Policy Requests

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Some Omni Gateway policies make outgoing requests to HTTP and gRPC upstream services. For example,
the [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-oauth-token-introspection) sends token
validation requests to an OAuth 2.0 service, and the
[External Authorization Policy](https://docs.mulesoft.com/gateway/latest/policies-included-external-authorization) forwards incoming client
requests to an authorization service.

By default, Managed and Self-Managed Omni Gateways protect these connections with a default TLS
Context. The default TLS context is not mTLS and uses the default ciphers listed in
[TLS Cipher Support on Omni Gateway](#local-support).

To override the default TLS context, configure a custom default TLS context for all outgoing
requests from policies. You can’t configure a custom default TLS context for Managed Omni Gateway.

## Configure a TLS Context for Self-Managed Gateways

For both local and connected mode, use a YAML configuration file to configure TLS between a policy
and an upstream service:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: default-tls spec:
defaultTLS: outboundPolicyCalls: skipValidation: <boolean> // OPTIONAL trustedCA: <string> #
OPTIONAL, defaults to the CA of operating systems certificate: // OPTIONAL key: <string> // OPTIONAL
crt: <string> // OPTIONAL alpn: <array> // OPTIONAL minversion: <string> // OPTIONAL maxversion:
<string> // OPTIONAL ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, ensure that your API upstream supports the listed ciphers.
For the supported ciphers, see [TLS Cipher Support on Omni Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the upstream certificate is not validated.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the upstream server certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate to present for mTLS. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

<!-- document id=6ca4a16ed1d4c6e37eec6f3e9c4c5a0cecb5f7bf0fc39d8a22bed0209f160f26 url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-api-key.md -->

---
product: Omni Gateway
version: 1.12
keywords: api key, client credentials, authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection API Key Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection API Key</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects an API key or client credentials headers into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.10.2</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection API Key policy injects authentication credentials into upstream requests to
authenticate with upstream services that require API key or client credential authentication. The
policy supports two authentication types:

- **API Key**: Injects an API key value into the `Authorization` header or a custom header.

- **Client ID and Secret**: Injects the client ID and client secret value into the `client_id` and
  `client_secret` headers or custom headers.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-api-key-flex config: authType: <string> // REQUIRED
overwrite: <boolean> // REQUIRED, default: true # For API Key authentication: apiKey: <string> //
REQUIRED when authType is "apiKey" customHeader: <string> // OPTIONAL when authType is "apiKey" #
For Client Credentials authentication: clientId: <string> // REQUIRED when authType is
"clientCredentials" clientSecret: <string> // REQUIRED when authType is "clientCredentials"
customClientIdHeader: <string> // OPTIONAL when authType is "clientCredentials"
customClientSecretHeader: <string> // OPTIONAL when authType is "clientCredentials"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>authType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>apiKey</code></p></div></div></td><td><div><div><p>Authentication type to inject, either <code>apiKey</code> or <code>clientCredentials</code>.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Overwrite authentication headers if present in the request.</p></div></div></td></tr><tr><td><div><div><p><code>apiKey</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>apiKey</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The API key value to inject.</p></div></div></td></tr><tr><td><div><div><p><code>customHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header name instead of <code>Authorization</code> for API key injection.</p></div></div></td></tr><tr><td><div><div><p><code>clientId</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>clientCredentials</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client ID to inject.</p></div></div></td></tr><tr><td><div><div><p><code>clientSecret</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>clientCredentials</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client secret to inject.</p></div></div></td></tr><tr><td><div><div><p><code>customClientIdHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>client_id</code> for client ID injection.</p></div></div></td></tr><tr><td><div><div><p><code>customClientSecretHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>client_secret</code> for client secret injection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Examples

- API Key:

  \- policyRef: name: credential-injection-api-key-flex config: authType: apiKey apiKey:
  my-secret-api-key overwrite: true

- API Key with Custom Header:

  \- policyRef: name: credential-injection-api-key-flex config: authType: apiKey apiKey:
  my-secret-api-key customHeader: X-API-Key overwrite: false

- Client Credentials:

  \- policyRef: name: credential-injection-api-key-flex config: authType: clientCredentials
  clientId: my-client-id clientSecret: my-client-secret overwrite: true

- Client Credentials with Custom Headers:

  \- policyRef: name: credential-injection-api-key-flex config: authType: clientCredentials
  clientId: my-client-id clientSecret: my-client-secret customClientIdHeader: X-Client-ID
  customClientSecretHeader: X-Client-Secret overwrite: false

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><p><strong>Authentication Type</strong></p></td><td><p>Type of authentication header to inject: <strong>API Key</strong> or <strong>Client ID and Secret</strong>.</p></td></tr><tr><td><p><strong>Overwrite headers</strong></p></td><td><p>Overwrite authentication headers if present in the request.</p></td></tr><tr><td><p><strong>API Key</strong></p></td><td><p>The API key value to inject.</p></td></tr><tr><td><p><strong>Custom header</strong></p></td><td><p>Use a custom header instead of Authorization for API key injection.</p></td></tr><tr><td><p><strong>Client ID</strong></p></td><td><p>The client ID to inject.</p></td></tr><tr><td><p><strong>Client Secret</strong></p></td><td><p>The client secret to inject.</p></td></tr><tr><td><p><strong>Custom Client ID header</strong></p></td><td><p>Use a custom header instead of <code>client_id</code> for client ID injection.</p></td></tr><tr><td><p><strong>Custom Client secret header</strong></p></td><td><p>Use a custom header instead of <code>client_secret</code> for client secret injection.</p></td></tr></tbody></table>

<!-- document id=68576675ac215fc2f45d13dc353011eef5edf21ad28e64967eda79adbd7946c5 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-api-key.md -->

---
product: Omni Gateway
version: 1.13
keywords: api key, client credentials, authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection API Key Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection API Key</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects an API key or client credentials headers into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.10.2</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-api-key-release-notes">Credential Injection API Key</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection API Key policy injects authentication credentials into upstream requests to
authenticate with upstream services that require API key or client credential authentication. The
policy supports two authentication types:

- **API Key**: Injects an API key value into the `Authorization` header or a custom header.

- **Client ID and Secret**: Injects the client ID and client secret value into the `client_id` and
  `client_secret` headers or custom headers.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-api-key-flex config: authType: <string> // REQUIRED
overwrite: <boolean> // REQUIRED, default: true # For API Key authentication: apiKey: <string> //
REQUIRED when authType is "apiKey" customHeader: <string> // OPTIONAL when authType is "apiKey" #
For Client Credentials authentication: clientId: <string> // REQUIRED when authType is
"clientCredentials" clientSecret: <string> // REQUIRED when authType is "clientCredentials"
customClientIdHeader: <string> // OPTIONAL when authType is "clientCredentials"
customClientSecretHeader: <string> // OPTIONAL when authType is "clientCredentials"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>authType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>apiKey</code></p></div></div></td><td><div><div><p>Authentication type to inject, either <code>apiKey</code> or <code>clientCredentials</code>.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Overwrite authentication headers if present in the request.</p></div></div></td></tr><tr><td><div><div><p><code>apiKey</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>apiKey</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The API key value to inject.</p></div></div></td></tr><tr><td><div><div><p><code>customHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header name instead of <code>Authorization</code> for API key injection.</p></div></div></td></tr><tr><td><div><div><p><code>clientId</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>clientCredentials</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client ID to inject.</p></div></div></td></tr><tr><td><div><div><p><code>clientSecret</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>clientCredentials</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client secret to inject.</p></div></div></td></tr><tr><td><div><div><p><code>customClientIdHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>client_id</code> for client ID injection.</p></div></div></td></tr><tr><td><div><div><p><code>customClientSecretHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>client_secret</code> for client secret injection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Examples

- API Key:

  \- policyRef: name: credential-injection-api-key-flex config: authType: apiKey apiKey:
  my-secret-api-key overwrite: true

- API Key with Custom Header:

  \- policyRef: name: credential-injection-api-key-flex config: authType: apiKey apiKey:
  my-secret-api-key customHeader: X-API-Key overwrite: false

- Client Credentials:

  \- policyRef: name: credential-injection-api-key-flex config: authType: clientCredentials
  clientId: my-client-id clientSecret: my-client-secret overwrite: true

- Client Credentials with Custom Headers:

  \- policyRef: name: credential-injection-api-key-flex config: authType: clientCredentials
  clientId: my-client-id clientSecret: my-client-secret customClientIdHeader: X-Client-ID
  customClientSecretHeader: X-Client-Secret overwrite: false

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><p><strong>Authentication Type</strong></p></td><td><p>Type of authentication header to inject: <strong>API Key</strong> or <strong>Client ID and Secret</strong>.</p></td></tr><tr><td><p><strong>Overwrite headers</strong></p></td><td><p>Overwrite authentication headers if present in the request.</p></td></tr><tr><td><p><strong>API Key</strong></p></td><td><p>The API key value to inject.</p></td></tr><tr><td><p><strong>Custom header</strong></p></td><td><p>Use a custom header instead of Authorization for API key injection.</p></td></tr><tr><td><p><strong>Client ID</strong></p></td><td><p>The client ID to inject.</p></td></tr><tr><td><p><strong>Client Secret</strong></p></td><td><p>The client secret to inject.</p></td></tr><tr><td><p><strong>Custom Client ID header</strong></p></td><td><p>Use a custom header instead of <code>client_id</code> for client ID injection.</p></td></tr><tr><td><p><strong>Custom Client secret header</strong></p></td><td><p>Use a custom header instead of <code>client_secret</code> for client secret injection.</p></td></tr></tbody></table>

<!-- document id=732a91cec946632baf8a3991b8077f19799e838ab20a67978464176139fafdab url=/mulesoft/current/en-us/gateway/latest/policies-outbound-api-key.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api key, client credentials, authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection API Key Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection API Key</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects an API key or client credentials headers into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.10.2</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-api-key-release-notes">Credential Injection API Key</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection API Key policy injects authentication credentials into upstream requests to
authenticate with upstream services that require API key or client credential authentication. The
policy supports two authentication types:

- **API Key**: Injects an API key value into the `Authorization` header or a custom header.

- **Client ID and Secret**: Injects the client ID and client secret value into the `client_id` and
  `client_secret` headers or custom headers.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-api-key-flex config: authType: <string> // REQUIRED
overwrite: <boolean> // REQUIRED, default: true # For API Key authentication: apiKey: <string> //
REQUIRED when authType is "apiKey" customHeader: <string> // OPTIONAL when authType is "apiKey" #
For Client Credentials authentication: clientId: <string> // REQUIRED when authType is
"clientCredentials" clientSecret: <string> // REQUIRED when authType is "clientCredentials"
customClientIdHeader: <string> // OPTIONAL when authType is "clientCredentials"
customClientSecretHeader: <string> // OPTIONAL when authType is "clientCredentials"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>authType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>apiKey</code></p></div></div></td><td><div><div><p>Authentication type to inject, either <code>apiKey</code> or <code>clientCredentials</code>.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Overwrite authentication headers if present in the request.</p></div></div></td></tr><tr><td><div><div><p><code>apiKey</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>apiKey</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The API key value to inject.</p></div></div></td></tr><tr><td><div><div><p><code>customHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header name instead of <code>Authorization</code> for API key injection.</p></div></div></td></tr><tr><td><div><div><p><code>clientId</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>clientCredentials</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client ID to inject.</p></div></div></td></tr><tr><td><div><div><p><code>clientSecret</code></p></div></div></td><td><div><div><p>Required when <code>authType</code> is <code>clientCredentials</code>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client secret to inject.</p></div></div></td></tr><tr><td><div><div><p><code>customClientIdHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>client_id</code> for client ID injection.</p></div></div></td></tr><tr><td><div><div><p><code>customClientSecretHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>client_secret</code> for client secret injection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Examples

- API Key:

  \- policyRef: name: credential-injection-api-key-flex config: authType: apiKey apiKey:
  my-secret-api-key overwrite: true

- API Key with Custom Header:

  \- policyRef: name: credential-injection-api-key-flex config: authType: apiKey apiKey:
  my-secret-api-key customHeader: X-API-Key overwrite: false

- Client Credentials:

  \- policyRef: name: credential-injection-api-key-flex config: authType: clientCredentials
  clientId: my-client-id clientSecret: my-client-secret overwrite: true

- Client Credentials with Custom Headers:

  \- policyRef: name: credential-injection-api-key-flex config: authType: clientCredentials
  clientId: my-client-id clientSecret: my-client-secret customClientIdHeader: X-Client-ID
  customClientSecretHeader: X-Client-Secret overwrite: false

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><p><strong>Authentication Type</strong></p></td><td><p>Type of authentication header to inject: <strong>API Key</strong> or <strong>Client ID and Secret</strong>.</p></td></tr><tr><td><p><strong>Overwrite headers</strong></p></td><td><p>Overwrite authentication headers if present in the request.</p></td></tr><tr><td><p><strong>API Key</strong></p></td><td><p>The API key value to inject.</p></td></tr><tr><td><p><strong>Custom header</strong></p></td><td><p>Use a custom header instead of Authorization for API key injection.</p></td></tr><tr><td><p><strong>Client ID</strong></p></td><td><p>The client ID to inject.</p></td></tr><tr><td><p><strong>Client Secret</strong></p></td><td><p>The client secret to inject.</p></td></tr><tr><td><p><strong>Custom Client ID header</strong></p></td><td><p>Use a custom header instead of <code>client_id</code> for client ID injection.</p></td></tr><tr><td><p><strong>Custom Client secret header</strong></p></td><td><p>Use a custom header instead of <code>client_secret</code> for client secret injection.</p></td></tr></tbody></table>

<!-- document id=0ba4475fc20ff68c2a8af33c7f6be71954828ab63a2925ae3daf05106ac8605c url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-basic-auth.md -->

---
product: Omni Gateway
version: 1.12
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection Basic Authentication Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection Basic Authentication</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects a basic authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection Basic Authentication policy injects an `Authorization` header containing a
username and password into outbound requests. The policy ensures that requests sent from Flex
Gateway to an upstream service include the correct authentication headers. The Authorization header
format is `Authorization: Basic <username:password>`.

The policy follows [Basic HTTP authentication standards](https://tools.ietf.org/html/rfc7617).

When an error occurs, the policy returns a `WWW-Authenticate` HTTP header field.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-basic-auth-flex config: username: <string> // OPTIONAL
password: <string> // OPTIONAL overwrite: <boolean> // OPTIONAL customHeader: <string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The username for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The password for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></div></div></td></tr><tr><td><div><div><p><code>customHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>Username</p></td><td><p>The username for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Password</p></td><td><p>The password for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Custom Header</p></td><td><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></td><td><p>Optional</p></td></tr></tbody></table>

<!-- document id=5ba980dc866eafffaf80ae9538a8edfe778b6cdab72bb2c05d346441fc892d28 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-basic-auth.md -->

---
product: Omni Gateway
version: 1.13
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection Basic Authentication Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection Basic Authentication</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects a basic authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-basic-auth-release-notes">Credential Injection Basic Authentication</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection Basic Authentication policy injects an `Authorization` header containing a
username and password into outbound requests. The policy ensures that requests sent from Omni
Gateway to an upstream service include the correct authentication headers. The Authorization header
format is `Authorization: Basic <username:password>`.

The policy follows [Basic HTTP authentication standards](https://tools.ietf.org/html/rfc7617).

When an error occurs, the policy returns a `WWW-Authenticate` HTTP header field.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-basic-auth-flex config: username: <string> // OPTIONAL
password: <string> // OPTIONAL overwrite: <boolean> // OPTIONAL customHeader: <string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The username for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The password for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></div></div></td></tr><tr><td><div><div><p><code>customHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>Username</p></td><td><p>The username for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Password</p></td><td><p>The password for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Custom Header</p></td><td><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></td><td><p>Optional</p></td></tr></tbody></table>

<!-- document id=1fb5e2c9608ece65c193db3ab73b5ecb3778a4a97c72521b3f2e8319f912545d url=/mulesoft/current/en-us/gateway/1.9/policies-outbound-basic-auth.md -->

---
product: Omni Gateway
version: 1.9
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection Basic Authentication Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection Basic Authentication</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects a basic authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection Basic Authentication policy injects an `Authorization` header containing a
username and password into outbound requests. The policy ensures that requests sent from Flex
Gateway to an upstream service include the correct authentication headers. The Authorization header
format is `Authorization: Basic <username:password>`.

The policy follows
[Basic HTTP authentication standards](https://datatracker.ietf.org/doc/html/rfc7617).

When an error occurs, the policy returns a `WWW-Authenticate` HTTP header field.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: credential-injection-basic-auth-flex config: username: <string> // OPTIONAL
password: <string> // OPTIONAL overwrite: <boolean> // OPTIONAL customHeader: <string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The username for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The password for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></div></div></td></tr><tr><td><div><div><p><code>customHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>Username</p></td><td><p>The username for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Password</p></td><td><p>The password for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Custom Header</p></td><td><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></td><td><p>Optional</p></td></tr></tbody></table>

<!-- document id=b0fe8cdbe6d37faa5b3e8b78eb8661d4bb449a4c6fc025c40b942998c7370ac7 url=/mulesoft/current/en-us/gateway/latest/policies-outbound-basic-auth.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection Basic Authentication Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection Basic Authentication</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects a basic authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-basic-auth-release-notes">Credential Injection Basic Authentication</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection Basic Authentication policy injects an `Authorization` header containing a
username and password into outbound requests. The policy ensures that requests sent from Omni
Gateway to an upstream service include the correct authentication headers. The Authorization header
format is `Authorization: Basic <username:password>`.

The policy follows [Basic HTTP authentication standards](https://tools.ietf.org/html/rfc7617).

When an error occurs, the policy returns a `WWW-Authenticate` HTTP header field.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-basic-auth-flex config: username: <string> // OPTIONAL
password: <string> // OPTIONAL overwrite: <boolean> // OPTIONAL customHeader: <string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The username for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The password for the basic authentication credentials.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></div></div></td></tr><tr><td><div><div><p><code>customHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>Username</p></td><td><p>The username for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Password</p></td><td><p>The password for the basic authentication credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, if the <code>Authorization</code> header is present, the policy overwrites it with the configured credentials.</p></td><td><p>Optional</p></td></tr><tr><td><p>Custom Header</p></td><td><p>When configured, a custom header is injected instead of the <code>Authorization</code> header. If <strong>Overwrite header</strong> is enabled, the policy overwrites the custom header if present instead of the <code>Authorization</code> header.</p></td><td><p>Optional</p></td></tr></tbody></table>

<!-- document id=4dc5468cba7fbcaaf37d4b26f199f74350e5f63a7d386e928f6ad23910d27d2b url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-jwt-generation.md -->

---
product: Omni Gateway
version: 1.12
keywords: jwt, token, authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection JWT Generation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection JWT Generation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Generates and injects a JWT token into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection JWT Generation policy generates and injects a JWT token into outgoing
requests. It signs the token with the configured key and algorithm and supports standard time-based
claims, such as `exp`, `iat`, and `nbf`, in addition to custom claims and JWT headers. Each claim
and header name and value can be a string or a DataWeave expression. Expressions can reference
request attributes or authentication data.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: jwt-generation-flex config: signingMethod: <string> // REQUIRED, default: RS256
privateKey: <string> // REQUIRED iat: <boolean> // REQUIRED, default: true exp: <number> //
REQUIRED, default: 0 nbf: <number> // REQUIRED, default: 0 customClaims: // REQUIRED (can be empty
array) - name: <string> value: <string> customHeaders: // REQUIRED (can be empty array) - name:
<string> value: <string>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>signingMethod</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>RS256</code></p></div></div></td><td><div><div><p>The algorithm that signs the JWT. Supported values: <code>RS256</code>, <code>RS384</code>, <code>RS512</code>, <code>HS256</code>, <code>HS384</code>, <code>HS512</code>, <code>ES256</code>, and <code>ES384</code>.</p></div></div></td></tr><tr><td><div><div><p><code>privateKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The key that signs the JWT. Use PEM-formatted pkcs8 for RSA and ES. Use plain text for HS.</p></div></div></td></tr><tr><td><div><div><p><code>iat</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A Boolean value specifying whether to include the issued-at (iat) claim in the JWT.</p></div></div></td></tr><tr><td><div><div><p><code>exp</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>0</code></p></div></div></td><td><div><div><p>The number of seconds from the issue time until expiration. To omit the <code>exp</code> claim, enter <code>0</code>.</p></div></div></td></tr><tr><td><div><div><p><code>nbf</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>0</code></p></div></div></td><td><div><div><p>The number of seconds from the issue time until the token becomes valid. To omit the <code>nbf</code> claim, enter <code>0</code>.</p></div></div></td></tr><tr><td><div><div><p><code>customClaims</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The claims to include in the JWT. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></div></div></td></tr><tr><td><div><div><p><code>customHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The JWT header parameters to include. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Examples

- HMAC-signed JWT with custom claim:

  \- policyRef: name: jwt-generation-flex config: signingMethod: HS256 privateKey: my-secret-key
  iat: true exp: 3600 nbf: 0 customClaims: - name: "sub" value:
  "#\[authentication.properties.clientId default 'anonymous'\]" customHeaders: \[\]

- RSA-signed JWT with custom claims and headers:

  \- policyRef: name: jwt-generation-flex config: signingMethod: RS256 privateKey: | -----BEGIN
  PRIVATE KEY----- <your-private-key> -----END PRIVATE KEY----- iat: true exp: 7200 nbf: 0
  customClaims: - name: "aud" value: "'https://upstream.example.com'" - name: "client\_id" value:
  "#\[authentication.properties.clientId\]" customHeaders: - name: "kid" value: "'key-1'"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>Signing Method</p></td><td><p>The algorithm that signs the JWT. Valid values are RS256, RS384, RS512, HS256, HS384, HS512, ES256, and ES384.</p></td><td><p>Required</p></td></tr><tr><td><p>Private Key</p></td><td><p>The key that signs the JWT. Use PEM with pkcs8 for RSA and ES. Use plain text for HS.</p></td><td><p>Required</p></td></tr><tr><td><p>Issued At (iat)</p></td><td><p>A Boolean value specifying whether to include the issued-at (<code>iat</code>) claim in the JWT.</p></td><td><p>Required</p></td></tr><tr><td><p>Expiration (exp)</p></td><td><p>The number of seconds from the issue time until expiration. To omit the <code>exp</code> claim, enter <code>0</code>.</p></td><td><p>Required</p></td></tr><tr><td><p>Not Before (nbf)</p></td><td><p>The number of seconds from the issue time until the token becomes valid. To omit the <code>nbf</code> claim, enter <code>0</code>.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Claims</p></td><td><p>The claims to include in the JWT. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Headers</p></td><td><p>The JWT header parameters to include. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></td><td><p>Required</p></td></tr></tbody></table>

<!-- document id=6b68c07471f1931bb72693ea5e9b89539aedc042c3b426675f2cd4c3ca607451 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-jwt-generation.md -->

---
product: Omni Gateway
version: 1.13
keywords: jwt, token, authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection JWT Generation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection JWT Generation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Generates and injects a JWT token into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-jwt-generation-release-notes">Credential Injection JWT Generation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection JWT Generation policy generates and injects a JWT token into outgoing
requests. It signs the token with the configured key and algorithm and supports standard time-based
claims, such as `exp`, `iat`, and `nbf`, in addition to custom claims and JWT headers. Each claim
and header name and value can be a string or a DataWeave expression. Expressions can reference
request attributes or authentication data.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: jwt-generation-flex config: signingMethod: <string> // REQUIRED, default: RS256
privateKey: <string> // REQUIRED iat: <boolean> // REQUIRED, default: true exp: <number> //
REQUIRED, default: 0 nbf: <number> // REQUIRED, default: 0 customClaims: // REQUIRED (can be empty
array) - name: <string> value: <string> customHeaders: // REQUIRED (can be empty array) - name:
<string> value: <string>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>signingMethod</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>RS256</code></p></div></div></td><td><div><div><p>The algorithm that signs the JWT. Supported values: <code>RS256</code>, <code>RS384</code>, <code>RS512</code>, <code>HS256</code>, <code>HS384</code>, <code>HS512</code>, <code>ES256</code>, and <code>ES384</code>.</p></div></div></td></tr><tr><td><div><div><p><code>privateKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The key that signs the JWT. Use PEM-formatted pkcs8 for RSA and ES. Use plain text for HS.</p></div></div></td></tr><tr><td><div><div><p><code>iat</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A Boolean value specifying whether to include the issued-at (iat) claim in the JWT.</p></div></div></td></tr><tr><td><div><div><p><code>exp</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>0</code></p></div></div></td><td><div><div><p>The number of seconds from the issue time until expiration. To omit the <code>exp</code> claim, enter <code>0</code>.</p></div></div></td></tr><tr><td><div><div><p><code>nbf</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>0</code></p></div></div></td><td><div><div><p>The number of seconds from the issue time until the token becomes valid. To omit the <code>nbf</code> claim, enter <code>0</code>.</p></div></div></td></tr><tr><td><div><div><p><code>customClaims</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The claims to include in the JWT. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></div></div></td></tr><tr><td><div><div><p><code>customHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The JWT header parameters to include. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Examples

- HMAC-signed JWT with custom claim:

  \- policyRef: name: jwt-generation-flex config: signingMethod: HS256 privateKey: my-secret-key
  iat: true exp: 3600 nbf: 0 customClaims: - name: "sub" value:
  "#\[authentication.properties.clientId default 'anonymous'\]" customHeaders: \[\]

- RSA-signed JWT with custom claims and headers:

  \- policyRef: name: jwt-generation-flex config: signingMethod: RS256 privateKey: | -----BEGIN
  PRIVATE KEY----- <your-private-key> -----END PRIVATE KEY----- iat: true exp: 7200 nbf: 0
  customClaims: - name: "aud" value: "'https://upstream.example.com'" - name: "client\_id" value:
  "#\[authentication.properties.clientId\]" customHeaders: - name: "kid" value: "'key-1'"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>Signing Method</p></td><td><p>The algorithm that signs the JWT. Valid values are RS256, RS384, RS512, HS256, HS384, HS512, ES256, and ES384.</p></td><td><p>Required</p></td></tr><tr><td><p>Private Key</p></td><td><p>The key that signs the JWT. Use PEM with pkcs8 for RSA and ES. Use plain text for HS.</p></td><td><p>Required</p></td></tr><tr><td><p>Issued At (iat)</p></td><td><p>A Boolean value specifying whether to include the issued-at (<code>iat</code>) claim in the JWT.</p></td><td><p>Required</p></td></tr><tr><td><p>Expiration (exp)</p></td><td><p>The number of seconds from the issue time until expiration. To omit the <code>exp</code> claim, enter <code>0</code>.</p></td><td><p>Required</p></td></tr><tr><td><p>Not Before (nbf)</p></td><td><p>The number of seconds from the issue time until the token becomes valid. To omit the <code>nbf</code> claim, enter <code>0</code>.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Claims</p></td><td><p>The claims to include in the JWT. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Headers</p></td><td><p>The JWT header parameters to include. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></td><td><p>Required</p></td></tr></tbody></table>

<!-- document id=872bf3d0dbb485f91e4ce20e73c75c0e5de634228669209dd22db90f8e141166 url=/mulesoft/current/en-us/gateway/latest/policies-outbound-jwt-generation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: jwt, token, authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection JWT Generation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection JWT Generation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Generates and injects a JWT token into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-jwt-generation-release-notes">Credential Injection JWT Generation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection JWT Generation policy generates and injects a JWT token into outgoing
requests. It signs the token with the configured key and algorithm and supports standard time-based
claims, such as `exp`, `iat`, and `nbf`, in addition to custom claims and JWT headers. Each claim
and header name and value can be a string or a DataWeave expression. Expressions can reference
request attributes or authentication data.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: jwt-generation-flex config: signingMethod: <string> // REQUIRED, default: RS256
privateKey: <string> // REQUIRED iat: <boolean> // REQUIRED, default: true exp: <number> //
REQUIRED, default: 0 nbf: <number> // REQUIRED, default: 0 customClaims: // REQUIRED (can be empty
array) - name: <string> value: <string> customHeaders: // REQUIRED (can be empty array) - name:
<string> value: <string>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>signingMethod</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>RS256</code></p></div></div></td><td><div><div><p>The algorithm that signs the JWT. Supported values: <code>RS256</code>, <code>RS384</code>, <code>RS512</code>, <code>HS256</code>, <code>HS384</code>, <code>HS512</code>, <code>ES256</code>, and <code>ES384</code>.</p></div></div></td></tr><tr><td><div><div><p><code>privateKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The key that signs the JWT. Use PEM-formatted pkcs8 for RSA and ES. Use plain text for HS.</p></div></div></td></tr><tr><td><div><div><p><code>iat</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A Boolean value specifying whether to include the issued-at (iat) claim in the JWT.</p></div></div></td></tr><tr><td><div><div><p><code>exp</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>0</code></p></div></div></td><td><div><div><p>The number of seconds from the issue time until expiration. To omit the <code>exp</code> claim, enter <code>0</code>.</p></div></div></td></tr><tr><td><div><div><p><code>nbf</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>0</code></p></div></div></td><td><div><div><p>The number of seconds from the issue time until the token becomes valid. To omit the <code>nbf</code> claim, enter <code>0</code>.</p></div></div></td></tr><tr><td><div><div><p><code>customClaims</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The claims to include in the JWT. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></div></div></td></tr><tr><td><div><div><p><code>customHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The JWT header parameters to include. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Examples

- HMAC-signed JWT with custom claim:

  \- policyRef: name: jwt-generation-flex config: signingMethod: HS256 privateKey: my-secret-key
  iat: true exp: 3600 nbf: 0 customClaims: - name: "sub" value:
  "#\[authentication.properties.clientId default 'anonymous'\]" customHeaders: \[\]

- RSA-signed JWT with custom claims and headers:

  \- policyRef: name: jwt-generation-flex config: signingMethod: RS256 privateKey: | -----BEGIN
  PRIVATE KEY----- <your-private-key> -----END PRIVATE KEY----- iat: true exp: 7200 nbf: 0
  customClaims: - name: "aud" value: "'https://upstream.example.com'" - name: "client\_id" value:
  "#\[authentication.properties.clientId\]" customHeaders: - name: "kid" value: "'key-1'"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>Signing Method</p></td><td><p>The algorithm that signs the JWT. Valid values are RS256, RS384, RS512, HS256, HS384, HS512, ES256, and ES384.</p></td><td><p>Required</p></td></tr><tr><td><p>Private Key</p></td><td><p>The key that signs the JWT. Use PEM with pkcs8 for RSA and ES. Use plain text for HS.</p></td><td><p>Required</p></td></tr><tr><td><p>Issued At (iat)</p></td><td><p>A Boolean value specifying whether to include the issued-at (<code>iat</code>) claim in the JWT.</p></td><td><p>Required</p></td></tr><tr><td><p>Expiration (exp)</p></td><td><p>The number of seconds from the issue time until expiration. To omit the <code>exp</code> claim, enter <code>0</code>.</p></td><td><p>Required</p></td></tr><tr><td><p>Not Before (nbf)</p></td><td><p>The number of seconds from the issue time until the token becomes valid. To omit the <code>nbf</code> claim, enter <code>0</code>.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Claims</p></td><td><p>The claims to include in the JWT. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Headers</p></td><td><p>The JWT header parameters to include. Each entry has a <code>name</code> and a <code>value</code>. Each can be a string or a DataWeave expression. The array can be empty.</p></td><td><p>Required</p></td></tr></tbody></table>

<!-- document id=459b0e66472f1ccc1df008029c619ddf5065c2e1338a041143a24f67319fbc99 url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-oauth.md -->

---
product: Omni Gateway
version: 1.12
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection OAuth 2.0 Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection OAuth 2.0</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects an OAuth 2.0 authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection OAuth 2.0 policy injects an `Authorization` token from an OAuth 2.0 service
into a request as a header. You can use any third-party OAuth 2.0 Identify Provider (IdP), such as
Okta, AWS, Azure, or Google Cloud Platform. The policy allows for tokens based on the OAuth 2.0
Authorization Framework to be injected into requests without having to register an external IdP
server in Anypoint Platform.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-oauth2-flex config: oauthService: <string> // REQUIRED
grantType: <string> // REQUIRED, supported values: clientCredentials or password credentialLocation:
<string> // REQUIRED, supported values: body or header clientId: <string> // REQUIRED for
clientCredentials grant type clientSecret: <string> // REQUIRED for clientCredentials grant type
username: <string> // REQUIRED for password grant type password: <string> // REQUIRED for password
grant type scope: - <string> // OPTIONAL overwrite: <boolean> // REQUIRED tokenFetchTimeout:
<number> // REQUIRED allowRequestWithoutCredential: <boolean> // REQUIRED tokenRequestBodyFormat:
<string> // REQUIRED, supported values: json or urlEncoded upstreamTokenHeaderName: <string> //
OPTIONAL upstreamTokenPrefixName: <string> // OPTIONAL cachingTtl: <number> // REQUIRED
customRequestHeaders: // OPTIONAL - name: <string> value: <string>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>oauthService</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code><a href="https://oauth-server/tokens">https://oauth-server/tokens</a></code></p></div></div></td><td><div><div><p>URL of the OAuth 2.0 service.</p></div></div></td></tr><tr><td><div><div><p><code>grantType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>clientCredentials</code></p></div></div></td><td><div><div><p>OAuth2 grant type specifying the method used to obtain access tokens from the authorization server. Supported values: <code>clientCredentials</code> or <code>password</code>.</p></div></div></td></tr><tr><td><div><div><p><code>credentialLocation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>body</code></p></div></div></td><td><div><div><p>Location of the Client ID and Client Secret in the OAuth2 token request. Supported values: <code>body</code> or <code>header</code>.</p></div></div></td></tr><tr><td><div><div><p><code>clientId</code></p></div></div></td><td><div><div><p>Required for <code>clientCredentials</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client ID.</p></div></div></td></tr><tr><td><div><div><p><code>clientSecret</code></p></div></div></td><td><div><div><p>Required for <code>clientCredentials</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client Secret.</p></div></div></td></tr><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Required for <code>password</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Username for password grant type.</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Required for <code>password</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Password for password grant type.</p></div></div></td></tr><tr><td><div><div><p><code>scope</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Scopes to include in the token.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></div></div></td></tr><tr><td><div><div><p><code>tokenFetchTimeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div><div><p>Time in seconds to wait for the service to return the token.</p></div></div></td></tr><tr><td><div><div><p><code>allowRequestWithoutCredential</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When enabled, if the policy can’t retrieve the token, Flex Gateway still sends the request.</p></div></div></td></tr><tr><td><div><div><p><code>tokenRequestBodyFormat</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>urlEncoded</code></p></div></div></td><td><div><div><p>The format of the token request body. Valid values: <code>json</code> or <code>urlEncoded</code>.</p></div></div></td></tr><tr><td><div><div><p><code>upstreamTokenHeaderName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>Authorization</code>.</p></div></div></td></tr><tr><td><div><div><p><code>upstreamTokenPrefixName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom token prefix instead of <code>Bearer</code>.</p></div></div></td></tr><tr><td><div><div><p><code>cachingTtl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>Time to live for cached tokens in seconds. If 0, the policy uses the full <code>expires_in</code> value from OAuth response. If greater than 0, the policy uses the minimum of the <code>cachingTtl</code> value and <code>expires_in</code> divided by 2.</p></div></div></td></tr><tr><td><div><div><p><code>customRequestHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A list of custom headers to add to the token request. Each header must have a <code>name</code> and <code>value</code> property.</p></div></div></td></tr></tbody></table>

#### Client Credentials Configuration Example

\- policyRef: name: credential-injection-oauth2-flex config: oauthService:
<https://oauth-server/tokens> grantType: clientCredentials credentialLocation: body clientId: id
clientSecret: secret scope: - user overwrite: true tokenFetchTimeout: 20
allowRequestWithoutCredential: true tokenRequestBodyFormat: urlEncoded cachingTtl: 0

#### Password Configuration Example

\- policyRef: name: credential-injection-oauth2-flex config: oauthService:
<https://oauth-server/tokens> grantType: password credentialLocation: body clientId: id
clientSecret: secret username: myuser password: mypassword scope: - user - read overwrite: true
tokenFetchTimeout: 20 allowRequestWithoutCredential: true tokenRequestBodyFormat: urlEncoded
cachingTtl: 0

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>OAuth 2.0 service URL</p></td><td><p>URL of the OAuth 2.0 service.</p></td><td><p>Required</p></td></tr><tr><td><p>Grant Type</p></td><td><p>OAuth2 grant type specifying the method used to obtain access tokens from the authorization server. Valid values: Client Credentials or Password.</p></td><td><p>Required</p></td></tr><tr><td><p>Credential location</p></td><td><p>Location of the Client ID and Client Secret in the OAuth2 token request.</p></td><td><p>Required</p></td></tr><tr><td><p>Client ID</p></td><td><p>Client ID.</p></td><td><p>Required for Client Credentials grant type</p></td></tr><tr><td><p>Client secret</p></td><td><p>Client Secret.</p></td><td><p>Required for Client Credentials grant type</p></td></tr><tr><td><p>Username</p></td><td><p>Username for password grant type.</p></td><td><p>Required for Password grant type</p></td></tr><tr><td><p>Password</p></td><td><p>Password for password grant type.</p></td><td><p>Required for Password grant type</p></td></tr><tr><td><p>Scope</p></td><td><p>List of scopes to use for OAuth2 request.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></td><td><p>Required</p></td></tr><tr><td><p>Token fetch timeout</p></td><td><p>Time in seconds to wait for the service to return the token.</p></td><td><p>Required</p></td></tr><tr><td><p>Allow request without credential</p></td><td><p>When enabled, if the policy can’t retrieve the token, Flex Gateway still sends the request.</p></td><td><p>Required</p></td></tr><tr><td><p>Token Request Body Format</p></td><td><p>The format of the token request body. Valid values: URL Encoded or JSON.</p></td><td><p>Required</p></td></tr><tr><td><p>Upstream Custom header</p></td><td><p>Use a custom header instead of Authorization.</p></td><td><p>Optional</p></td></tr><tr><td><p>Upstream Custom Token Prefix</p></td><td><p>Use a custom token prefix instead of Bearer.</p></td><td><p>Optional</p></td></tr><tr><td><p>Caching TTL (seconds)</p></td><td><p>Time to live for cached tokens in seconds. If 0, the policy uses the full <code>expires_in</code> value from OAuth response. If greater than 0, the policy uses the minimum of the Caching TTL value and <code>expires_in</code> divided by 2.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Request Headers</p></td><td><p>A list of custom headers to add to the token request. Each header must have a name and value property.</p></td><td><p>Optional</p></td></tr></tbody></table>

<!-- document id=07bd54076b91b65deac8ce4063e3c24a02a9d2063d9ccc09556cb7c3b74475af url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-oauth.md -->

---
product: Omni Gateway
version: 1.13
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection OAuth 2.0 Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection OAuth 2.0</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects an OAuth 2.0 authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-release-notes">Credential Injection OAuth 2.0</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection OAuth 2.0 policy injects an `Authorization` token from an OAuth 2.0 service
into a request as a header. You can use any third-party OAuth 2.0 Identify Provider (IdP), such as
Okta, AWS, Azure, or Google Cloud Platform. The policy allows for tokens based on the OAuth 2.0
Authorization Framework to be injected into requests without having to register an external IdP
server in Anypoint Platform.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-oauth2-flex config: oauthService: <string> // REQUIRED
grantType: <string> // REQUIRED, supported values: clientCredentials or password credentialLocation:
<string> // REQUIRED, supported values: body or header clientId: <string> // REQUIRED for
clientCredentials grant type clientSecret: <string> // REQUIRED for clientCredentials grant type
username: <string> // REQUIRED for password grant type password: <string> // REQUIRED for password
grant type scope: - <string> // OPTIONAL overwrite: <boolean> // REQUIRED tokenFetchTimeout:
<number> // REQUIRED allowRequestWithoutCredential: <boolean> // REQUIRED tokenRequestBodyFormat:
<string> // REQUIRED, supported values: json or urlEncoded upstreamTokenHeaderName: <string> //
OPTIONAL upstreamTokenPrefixName: <string> // OPTIONAL cachingTtl: <number> // REQUIRED
customRequestHeaders: // OPTIONAL - name: <string> value: <string>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>oauthService</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code><a href="https://oauth-server/tokens">https://oauth-server/tokens</a></code></p></div></div></td><td><div><div><p>URL of the OAuth 2.0 service.</p></div></div></td></tr><tr><td><div><div><p><code>grantType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>clientCredentials</code></p></div></div></td><td><div><div><p>OAuth2 grant type specifying the method used to obtain access tokens from the authorization server. Supported values: <code>clientCredentials</code> or <code>password</code>.</p></div></div></td></tr><tr><td><div><div><p><code>credentialLocation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>body</code></p></div></div></td><td><div><div><p>Location of the Client ID and Client Secret in the OAuth2 token request. Supported values: <code>body</code> or <code>header</code>.</p></div></div></td></tr><tr><td><div><div><p><code>clientId</code></p></div></div></td><td><div><div><p>Required for <code>clientCredentials</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client ID.</p></div></div></td></tr><tr><td><div><div><p><code>clientSecret</code></p></div></div></td><td><div><div><p>Required for <code>clientCredentials</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client Secret.</p></div></div></td></tr><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Required for <code>password</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Username for password grant type.</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Required for <code>password</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Password for password grant type.</p></div></div></td></tr><tr><td><div><div><p><code>scope</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Scopes to include in the token.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></div></div></td></tr><tr><td><div><div><p><code>tokenFetchTimeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div><div><p>Time in seconds to wait for the service to return the token.</p></div></div></td></tr><tr><td><div><div><p><code>allowRequestWithoutCredential</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When enabled, if the policy can’t retrieve the token, Omni Gateway still sends the request.</p></div></div></td></tr><tr><td><div><div><p><code>tokenRequestBodyFormat</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>urlEncoded</code></p></div></div></td><td><div><div><p>The format of the token request body. Valid values: <code>json</code> or <code>urlEncoded</code>.</p></div></div></td></tr><tr><td><div><div><p><code>upstreamTokenHeaderName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>Authorization</code>.</p></div></div></td></tr><tr><td><div><div><p><code>upstreamTokenPrefixName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom token prefix instead of <code>Bearer</code>.</p></div></div></td></tr><tr><td><div><div><p><code>cachingTtl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>Time to live for cached tokens in seconds. If 0, the policy uses the full <code>expires_in</code> value from OAuth response. If greater than 0, the policy uses the minimum of the <code>cachingTtl</code> value and <code>expires_in</code> divided by 2.</p></div></div></td></tr><tr><td><div><div><p><code>customRequestHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A list of custom headers to add to the token request. Each header must have a <code>name</code> and <code>value</code> property.</p></div></div></td></tr></tbody></table>

#### Client Credentials Configuration Example

\- policyRef: name: credential-injection-oauth2-flex config: oauthService:
<https://oauth-server/tokens> grantType: clientCredentials credentialLocation: body clientId: id
clientSecret: secret scope: - user overwrite: true tokenFetchTimeout: 20
allowRequestWithoutCredential: true tokenRequestBodyFormat: urlEncoded cachingTtl: 0

#### Password Configuration Example

\- policyRef: name: credential-injection-oauth2-flex config: oauthService:
<https://oauth-server/tokens> grantType: password credentialLocation: body clientId: id
clientSecret: secret username: myuser password: mypassword scope: - user - read overwrite: true
tokenFetchTimeout: 20 allowRequestWithoutCredential: true tokenRequestBodyFormat: urlEncoded
cachingTtl: 0

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>OAuth 2.0 service URL</p></td><td><p>URL of the OAuth 2.0 service.</p></td><td><p>Required</p></td></tr><tr><td><p>Grant Type</p></td><td><p>OAuth2 grant type specifying the method used to obtain access tokens from the authorization server. Valid values: Client Credentials or Password.</p></td><td><p>Required</p></td></tr><tr><td><p>Credential location</p></td><td><p>Location of the Client ID and Client Secret in the OAuth2 token request.</p></td><td><p>Required</p></td></tr><tr><td><p>Client ID</p></td><td><p>Client ID.</p></td><td><p>Required for Client Credentials grant type</p></td></tr><tr><td><p>Client secret</p></td><td><p>Client Secret.</p></td><td><p>Required for Client Credentials grant type</p></td></tr><tr><td><p>Username</p></td><td><p>Username for password grant type.</p></td><td><p>Required for Password grant type</p></td></tr><tr><td><p>Password</p></td><td><p>Password for password grant type.</p></td><td><p>Required for Password grant type</p></td></tr><tr><td><p>Scope</p></td><td><p>List of scopes to use for OAuth2 request.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></td><td><p>Required</p></td></tr><tr><td><p>Token fetch timeout</p></td><td><p>Time in seconds to wait for the service to return the token.</p></td><td><p>Required</p></td></tr><tr><td><p>Allow request without credential</p></td><td><p>When enabled, if the policy can’t retrieve the token, Omni Gateway still sends the request.</p></td><td><p>Required</p></td></tr><tr><td><p>Token Request Body Format</p></td><td><p>The format of the token request body. Valid values: URL Encoded or JSON.</p></td><td><p>Required</p></td></tr><tr><td><p>Upstream Custom header</p></td><td><p>Use a custom header instead of Authorization.</p></td><td><p>Optional</p></td></tr><tr><td><p>Upstream Custom Token Prefix</p></td><td><p>Use a custom token prefix instead of Bearer.</p></td><td><p>Optional</p></td></tr><tr><td><p>Caching TTL (seconds)</p></td><td><p>Time to live for cached tokens in seconds. If 0, the policy uses the full <code>expires_in</code> value from OAuth response. If greater than 0, the policy uses the minimum of the Caching TTL value and <code>expires_in</code> divided by 2.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Request Headers</p></td><td><p>A list of custom headers to add to the token request. Each header must have a name and value property.</p></td><td><p>Optional</p></td></tr></tbody></table>

<!-- document id=9b2788205dee60d243d3b9dd785cd9592594ac509ec9b1e87d695966d7789b76 url=/mulesoft/current/en-us/gateway/1.9/policies-outbound-oauth.md -->

---
product: Omni Gateway
version: 1.9
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection OAuth 2.0 Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection OAuth 2.0</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects an OAuth 2.0 authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection OAuth 2.0 policy injects an `Authorization` token from an OAuth 2.0 service
into a request as a header. You can use any third-party OAuth 2.0 Identify Provider (IdP), such as
Okta, AWS, Azure, or Google Cloud Platform. The policy allows for tokens based on the OAuth 2.0
Authorization Framework to be injected into requests without having to register an external IdP
server in Anypoint Platform.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: credential-injection-oauth2-flex config: oauthService: <string> // REQUIRED
clientId: <string> // REQUIRED clientSecret: <string> // REQUIRED scope: - <string> // OPTIONAL
overwrite: <boolean> // OPTIONAL tokenFetchTimeout: <number> // OPTIONAL
allowRequestWithoutCredential: <boolean> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>oauthService</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code><a href="https://oauth-server/tokens">https://oauth-server/tokens</a></code></p></div></div></td><td><div><div><p>URL of the OAuth 2.0 service.</p></div></div></td></tr><tr><td><div><div><p><code>clientId</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client ID.</p></div></div></td></tr><tr><td><div><div><p><code>clientSecret</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client Secret.</p></div></div></td></tr><tr><td><div><div><p><code>scope</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Scopes to include in the token.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></div></div></td></tr><tr><td><div><div><p><code>tokenFetchTimeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div><div><p>Time in seconds to wait for the service to return the token.</p></div></div></td></tr><tr><td><div><div><p><code>allowRequestWithoutCredential</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When enabled, if the policy can’t retrieve the token, Flex Gateway still sends the request.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: credential-injection-oauth2-flex config: oauthService:
<https://oauth-server/tokens> clientId: id clientSecret: secret scope: - user tokenFetchTimeout: 20
allowRequestWithoutCredential: true

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>OAuth 2.0 service URL</p></td><td><p>URL of the OAuth 2.0 service.</p></td><td><p>Required</p></td></tr><tr><td><p>Client ID</p></td><td><p>Client ID.</p></td><td><p>Required</p></td></tr><tr><td><p>Client secret</p></td><td><p>Client Secret.</p></td><td><p>Required</p></td></tr><tr><td><p>Scope</p></td><td><p>Scopes to include in the token.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></td><td><p>Required</p></td></tr><tr><td><p>Token fetch timeout</p></td><td><p>Time in seconds to wait for the service to return the token.</p></td><td><p>Required</p></td></tr><tr><td><p>Allow request without credential</p></td><td><p>When enabled, if the policy can’t retrieve the token, Flex Gateway still sends the request.</p></td><td><p>Required</p></td></tr></tbody></table>

<!-- document id=4cada7350904e75c8b3c718d431292e46aa4de86671952579c8f099bc590cb71 url=/mulesoft/current/en-us/gateway/latest/policies-outbound-oauth.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Credential Injection OAuth 2.0 Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Credential Injection OAuth 2.0</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Injects an OAuth 2.0 authorization header into outgoing requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-release-notes">Credential Injection OAuth 2.0</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The Credential Injection OAuth 2.0 policy injects an `Authorization` token from an OAuth 2.0 service
into a request as a header. You can use any third-party OAuth 2.0 Identify Provider (IdP), such as
Okta, AWS, Azure, or Google Cloud Platform. The policy allows for tokens based on the OAuth 2.0
Authorization Framework to be injected into requests without having to register an external IdP
server in Anypoint Platform.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: credential-injection-oauth2-flex config: oauthService: <string> // REQUIRED
grantType: <string> // REQUIRED, supported values: clientCredentials or password credentialLocation:
<string> // REQUIRED, supported values: body or header clientId: <string> // REQUIRED for
clientCredentials grant type clientSecret: <string> // REQUIRED for clientCredentials grant type
username: <string> // REQUIRED for password grant type password: <string> // REQUIRED for password
grant type scope: - <string> // OPTIONAL overwrite: <boolean> // REQUIRED tokenFetchTimeout:
<number> // REQUIRED allowRequestWithoutCredential: <boolean> // REQUIRED tokenRequestBodyFormat:
<string> // REQUIRED, supported values: json or urlEncoded upstreamTokenHeaderName: <string> //
OPTIONAL upstreamTokenPrefixName: <string> // OPTIONAL cachingTtl: <number> // REQUIRED
customRequestHeaders: // OPTIONAL - name: <string> value: <string> customRequestBodyParameters: //
OPTIONAL - name: <string> value: <string> // string or DataWeave expression

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>oauthService</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code><a href="https://oauth-server/tokens">https://oauth-server/tokens</a></code></p></div></div></td><td><div><div><p>URL of the OAuth 2.0 service.</p></div></div></td></tr><tr><td><div><div><p><code>grantType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>clientCredentials</code></p></div></div></td><td><div><div><p>OAuth2 grant type specifying the method used to obtain access tokens from the authorization server. Supported values: <code>clientCredentials</code> or <code>password</code>.</p></div></div></td></tr><tr><td><div><div><p><code>credentialLocation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>body</code></p></div></div></td><td><div><div><p>Location of the Client ID and Client Secret in the OAuth2 token request. Supported values: <code>body</code> or <code>header</code>.</p></div></div></td></tr><tr><td><div><div><p><code>clientId</code></p></div></div></td><td><div><div><p>Required for <code>clientCredentials</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client ID.</p></div></div></td></tr><tr><td><div><div><p><code>clientSecret</code></p></div></div></td><td><div><div><p>Required for <code>clientCredentials</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Client Secret.</p></div></div></td></tr><tr><td><div><div><p><code>username</code></p></div></div></td><td><div><div><p>Required for <code>password</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Username for password grant type.</p></div></div></td></tr><tr><td><div><div><p><code>password</code></p></div></div></td><td><div><div><p>Required for <code>password</code> grant type</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Password for password grant type.</p></div></div></td></tr><tr><td><div><div><p><code>scope</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Scopes to include in the token.</p></div></div></td></tr><tr><td><div><div><p><code>overwrite</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></div></div></td></tr><tr><td><div><div><p><code>tokenFetchTimeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div><div><p>Time in seconds to wait for the service to return the token.</p></div></div></td></tr><tr><td><div><div><p><code>allowRequestWithoutCredential</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When enabled, if the policy can’t retrieve the token, Omni Gateway still sends the request.</p></div></div></td></tr><tr><td><div><div><p><code>tokenRequestBodyFormat</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>urlEncoded</code></p></div></div></td><td><div><div><p>The format of the token request body. Valid values: <code>json</code> or <code>urlEncoded</code>.</p></div></div></td></tr><tr><td><div><div><p><code>upstreamTokenHeaderName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom header instead of <code>Authorization</code>.</p></div></div></td></tr><tr><td><div><div><p><code>upstreamTokenPrefixName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Use a custom token prefix instead of <code>Bearer</code>.</p></div></div></td></tr><tr><td><div><div><p><code>cachingTtl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>Time to live for cached tokens in seconds. If 0, the policy uses the full <code>expires_in</code> value from OAuth response. If greater than 0, the policy uses the minimum of the <code>cachingTtl</code> value and <code>expires_in</code> divided by 2.</p></div></div></td></tr><tr><td><div><div><p><code>customRequestHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A list of custom headers to add to the token request. Each header must have a <code>name</code> and <code>value</code> property.</p></div></div></td></tr><tr><td><div><div><p><code>customRequestBodyParameters</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A list of custom parameters to add to the token request body, such as <code>audience</code>. Each parameter must have a <code>name</code> and <code>value</code> property. The <code>value</code> can be a static string or a DataWeave expression.</p></div></div></td></tr></tbody></table>

#### Client Credentials Configuration Example

\- policyRef: name: credential-injection-oauth2-flex config: oauthService:
<https://oauth-server/tokens> grantType: clientCredentials credentialLocation: body clientId: id
clientSecret: secret scope: - user overwrite: true tokenFetchTimeout: 20
allowRequestWithoutCredential: true tokenRequestBodyFormat: urlEncoded cachingTtl: 0

#### Password Configuration Example

\- policyRef: name: credential-injection-oauth2-flex config: oauthService:
<https://oauth-server/tokens> grantType: password credentialLocation: body clientId: id
clientSecret: secret username: myuser password: mypassword scope: - user - read overwrite: true
tokenFetchTimeout: 20 allowRequestWithoutCredential: true tokenRequestBodyFormat: urlEncoded
cachingTtl: 0

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><p>OAuth 2.0 service URL</p></td><td><p>URL of the OAuth 2.0 service.</p></td><td><p>Required</p></td></tr><tr><td><p>Grant Type</p></td><td><p>OAuth2 grant type specifying the method used to obtain access tokens from the authorization server. Valid values: Client Credentials or Password.</p></td><td><p>Required</p></td></tr><tr><td><p>Credential location</p></td><td><p>Location of the Client ID and Client Secret in the OAuth2 token request.</p></td><td><p>Required</p></td></tr><tr><td><p>Client ID</p></td><td><p>Client ID.</p></td><td><p>Required for Client Credentials grant type</p></td></tr><tr><td><p>Client secret</p></td><td><p>Client Secret.</p></td><td><p>Required for Client Credentials grant type</p></td></tr><tr><td><p>Username</p></td><td><p>Username for password grant type.</p></td><td><p>Required for Password grant type</p></td></tr><tr><td><p>Password</p></td><td><p>Password for password grant type.</p></td><td><p>Required for Password grant type</p></td></tr><tr><td><p>Scope</p></td><td><p>List of scopes to use for OAuth2 request.</p></td><td><p>Optional</p></td></tr><tr><td><p>Overwrite header</p></td><td><p>When enabled, the policy overwrites the <code>Authorization</code> header with a new authorization token if the header is present.</p></td><td><p>Required</p></td></tr><tr><td><p>Token fetch timeout</p></td><td><p>Time in seconds to wait for the service to return the token.</p></td><td><p>Required</p></td></tr><tr><td><p>Allow request without credential</p></td><td><p>When enabled, if the policy can’t retrieve the token, Omni Gateway still sends the request.</p></td><td><p>Required</p></td></tr><tr><td><p>Token Request Body Format</p></td><td><p>The format of the token request body. Valid values: URL Encoded or JSON.</p></td><td><p>Required</p></td></tr><tr><td><p>Upstream Custom header</p></td><td><p>Use a custom header instead of Authorization.</p></td><td><p>Optional</p></td></tr><tr><td><p>Upstream Custom Token Prefix</p></td><td><p>Use a custom token prefix instead of Bearer.</p></td><td><p>Optional</p></td></tr><tr><td><p>Caching TTL (seconds)</p></td><td><p>Time to live for cached tokens in seconds. If 0, the policy uses the full <code>expires_in</code> value from OAuth response. If greater than 0, the policy uses the minimum of the Caching TTL value and <code>expires_in</code> divided by 2.</p></td><td><p>Required</p></td></tr><tr><td><p>Custom Request Headers</p></td><td><p>A list of custom headers to add to the token request. Each header must have a name and value property.</p></td><td><p>Optional</p></td></tr><tr><td><p>Custom Request Body Parameters</p></td><td><p>A list of custom parameters to add to the token request body, such as <code>audience</code>. Each parameter must have a name and value property. The value can be a static string or a DataWeave expression.</p></td><td><p>Optional</p></td></tr></tbody></table>

<!-- document id=40bc215c171080fa5f6a026b66142aee2430ae02d7ae4ae8df8ba6e46643ddf9 url=/mulesoft/current/en-us/gateway/1.12/policies-included-cors.md -->

---
product: Omni Gateway
version: 1.12
keywords: cross origin resource sharing, cors, api gateway, flex gateway, gateway, policy
---

# Cross-Origin Resource Sharing (CORS) Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Cross-Origin Resource Sharing (CORS)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables access to resources residing in external domains</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Compliance</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy</p></div></div></td></tr></tbody></table>

## Summary

CORS is a mechanism by which a web application can access resources that are defined in another
domain. Browsers implement this standard by default. The CORS policy complies with the
[CORS W3C recommendation](https://fetch.spec.whatwg.org/) standards.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: cors-flex config: originGroups: <array> // OPTIONAL, default: \[\] - origins:
accessControlMaxAge: allowedMethods: methodName: - isAllowed: headers: <array> // OPTIONAL, default:
\[\] exposedHeaders: <array> // OPTIONAL, default: \[\] publicResource: <bool> // OPTIONAL, default:
true supportCredentials: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>originGroups</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List containing groups of origins</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of origins to be included in the group. For example, <code>http://www.the-origin-of-time.com</code></p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.accessControlMaxAge</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>30</p></div></div></td><td><div><div><p>Duration in seconds that a preflight response can be cached without sending another preflight request</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>CONNECT, DELETE, GET, OPTIONS, PATCH, POST, PUT, TRACE</p></div></div></td><td><div><div><p>Allowed HTTP methods</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Method name</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName.isAllowed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A boolean indicating if a method is allowed</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>HTTP headers used for preflight requests</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.exposedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Headers that browser JavaScript is allowed to access</p></div></div></td></tr><tr><td><div><div><p><code>publicResource</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A boolean indicating if the CORS configuration is to be applied as a public resource</p></div></div></td></tr><tr><td><div><div><p><code>supportCredentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>A boolean indicating if the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: cors-flex config: publicResource: false supportCredentials: true originGroups: -
origins: - http://www.the-origin-of-time.com accessControlMaxAge: 30 allowedMethods: - isAllowed:
true methodName: POST - isAllowed: true methodName: PUT - isAllowed: true methodName: GET -
isAllowed: false methodName: CONNECT - isAllowed: false methodName: DELETE - isAllowed: false
methodName: OPTIONS - isAllowed: false methodName: PATCH - isAllowed: false methodName: TRACE
headers: - x-allow-origin - x-yet-another-valid-header exposedHeaders: - x-forwarded-for

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Public resource</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied as a public resource (default)</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default group</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied only to specific resources (requires unselecting <strong>Public resource</strong>)</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Support credentials</p></div></div></td><td><div><div><p>Whether the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## Why CORS

CORS enables you to achieve web page security and web integrity in your environment. To know why you
might need to apply the CORS policy to your backend, you must first understand _origins_, _cookies_,
and how they can be manipulated to violate web page integrity.

### Introduction to the Web Origin Concept

Origin is a header that specifies the request that initiated the fetch. The origin header includes
only the server name (no path information). At a very basic level, an origin consists of:

- URI scheme: `http://`

- Host name: `www.example.com`

- Port number: `8080`

For requests between any two [origin](#origins) to be approved, the origins must be equal. Origins
are considered equal only if all these three parameters match. For more information, see
[RFC 6454 - The Web Origin Concept](https://tools.ietf.org/html/rfc6454).

### HTTP Cookies

Websites use HTTP cookies to retain stateful information. Most commonly, web servers use
authentication cookies to know whether a user is logged in, and to know which account users are
logged in to. For more information, see [RFC 6265](https://www.ietf.org/rfc/rfc6265.txt).

SOP (same-origin policy) deters malicious attackers from exploiting cookies when one web page
invokes another. For example, you might log in to your bank’s web page using a cookie that an
attacker might be able to obtain and exploit to query the bank’s API on your behalf.

With the SOP, scripts can access data from a target web page only if it has the same origin as the
caller web page. For more information about origins, see
[Wikipedia](https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules).

Because the SOP is highly restrictive, access from one suborigin to another or to external
hyperlinks do not work on web pages. For example, if an origin `www.testapply.com` has two
suborigins, `www.eng.testapply.com` and `www.docs.testapply.com`, communication between the two
suborigins is denied. Additionally, any hyperlinks to external websites from any of the suborigins
is also denied.

To circumvent this problem, web browsers implemented the CORS standard, which validates the web
server and accepts the request if the validation is successful.

For example, if your bank implements the CORS server-side protocol on its login server, you can
query data only directly from the bank’s web page. Any attempt to query the login API from an
external (non-bank) domain is denied.

## How CORS Works

When your web pages request data, the browser detects whether the request is from within same origin
and determines whether to apply the CORS algorithm. If you query data from a web page that is not in
your origin, then the CORS policy is applied.

The CORS algorithm works on the web server and on the client-side for the web page that requested
the information. The client-side algorithm in the CORS policy is implemented by:

- Determining whether the request is complex (and potentially dangerous) and sending a preliminary
  _preflight_ request to verify whether the server accepts the origin.

- Executing the actual request and validating that the server responds correctly and accepts the
  origin.

A _preflight_ is a preliminary request (using OPTIONS as the HTTP method) from the web browser to
the backend server to test the identity (origin and a few other headers) of the web page that is
trying to perform the request.

If the backend does not accept the origin, the backend server responds to the request without a
specific header (Access-Control-Allow-Origin). The client then understands that the page’s origin is
not allowed in that server and does not execute the actual request.

The following diagram shows the XMLHttpRequest (XHR) in a JavaScript flow for determining whether to
execute the actual request:

![A flowchart illustrating the process of standard latency and added latency for Javascript cross-domain XHR calls](/mulesoft/current/en-us/gateway/1.12/_images/cors-policy-xhr-diagram.png)

As illustrated in the diagram, the request is validated based on the communication between the
browser and the server:

- If the request is considered to be complex (see the previous client-side diagram for XHR), then a
  preflight request is executed.

  If the server does not return the proper CORS response headers for the preflight, the client
  library (XHR in the previous example) is not allowed to perform the actual request.

- If the preflight response is correct and complete, then the client library executes the actual
  request, which includes certain CORS headers.

  The client library then validates the CORS headers of the response. If some of the required
  headers are missing, then again the client library is obliged to block the response from reaching
  the client, which is usually a web page.

## CORS Components

You can configure various components of the CORS policy, such as request headers, response headers,
public resources and groups, ordering, and wildcards.

### CORS Request Headers

- Origin: The origin making the cross origin request.

- Access-Control-Request-Method: The method that is invoked in the actual request.

  This header is sent in the preflight request.

- Access-Control-Request-Headers: Custom headers that are sent in the actual request.

  This header is sent in the preflight request. For the GET or HEAD methods, the standard defines a
  specific list of headers that are considered simple enough to not require a preflight. For custom
  headers, a preflight is executed for GET and HEAD requests (see the previous XHR example to
  validate the path in which the client does not have to perform a preflight).

### CORS Response Headers

The headers included in a response depend on whether the request is a preflight or an actual
request:

- `Access-Control-Allow-Origin`: Obligatory in every response.

  If this header is not present in the response, the browser or client library blocks the response
  from reaching the web page. The wildcard “\*” can be used to represent any origin.

- `Access-Control-Allow-Methods`: Allowed methods that can be executed.

  This header is returned in the OPTIONS request (preflight). The server might respond with a list
  of allowed methods, delegating the validation task to the client.

- `Access-Control-Allow-Headers`: Allowed headers in the actual request.

  This header works in a manner similar to how Access-Control-Allow-Methods works .

- `Access-Control-Allow-Credentials`: Notifies the client whether the actual request can be made
  with a cookie.

  The `Access-Control-Allow-Credentials` returns a Boolean value.

- `Access-Control-Expose-Headers`: Provides the browser or client library with a list of headers
  that can be accessed by the web page that executed the request.

  The HTTP library performing the CORS request exposes only the headers to the web page, providing
  further privacy and security.

- `Access-Control-Max-Age`: Specifies the duration (in seconds) in which the browser can avoid
  performing a second preflight on a request.

### Public Resources and Groups

If you need to bypass the browser SOP, Mulesoft provides you an option to configure a public
resource that enables the API gateway policy to mirror the preflight data in the response. This
ensures that the actual request is correctly updated with all the CORS headers so that the browser
accepts the response.

If the public resource option is not secure enough for your environment, define multiple groups for
the different origins that query your API. Each group applies to a list of origins and can specify
different methods, headers, preflight caching time, and expose headers.

### Ordering

The CORS policy is always applied first by the API gateway, before any other policies can be
applied. If a protected request using OPTIONS is sent to an application that has the CORS policy
applied, the request does not reach the protected resource. According to the
[CORS specification](https://fetch.spec.whatwg.org/#resource-preflight-requests), all OPTIONS
requests are considered preflight.

### Configuration Wildcards

Wildcards (`*`) are accepted in the Origins and Headers sections of a group configuration. Use
wildcards when you need a public resource, but must restrict the accepted HTTP methods.

If you have configured multiple groups and one of the groups uses a wildcard origin, the
non-wildcard settings override the wildcard configurations.

## FAQs

**The CORS policy does not seem to be applied.**

If you use tools such as curl or Postman to test the CORS policy for a complex request, the CORS
request headers are not added and the preflight does not occur.

If no CORS headers are sent or improper headers are used in the request, the API gateway CORS policy
does not add any CORS response headers, giving the impression that the policy is not applied. Ensure
that you use the libraries that implement the CORS protocol specific to your environment, or review
the specification to ensure that you are configuring the correct headers.

<!-- document id=88372047498191adf6414d4cf33dddbaa1a70b7edd100e2470913bca43546eb8 url=/mulesoft/current/en-us/gateway/1.13/policies-included-cors.md -->

---
product: Omni Gateway
version: 1.13
keywords: cross origin resource sharing, cors, api gateway, flex gateway, gateway, policy
---

# Cross-Origin Resource Sharing (CORS) Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Cross-Origin Resource Sharing (CORS)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables access to resources residing in external domains</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Compliance</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/cors-release-notes">Cross-Origin Resource Sharing (CORS)</a></p></div></div></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy</p></div></div></td></tr></tbody></table>

## Summary

CORS is a mechanism by which a web application can access resources that are defined in another
domain. Browsers implement this standard by default. The CORS policy complies with the
[CORS W3C recommendation](https://fetch.spec.whatwg.org/) standards.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: cors-flex config: originGroups: <array> // OPTIONAL, default: \[\] - origins:
accessControlMaxAge: allowedMethods: methodName: - isAllowed: headers: <array> // OPTIONAL, default:
\[\] exposedHeaders: <array> // OPTIONAL, default: \[\] publicResource: <bool> // OPTIONAL, default:
true supportCredentials: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>originGroups</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List containing groups of origins</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of origins to be included in the group. For example, <code>http://www.the-origin-of-time.com</code></p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.accessControlMaxAge</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>30</p></div></div></td><td><div><div><p>Duration in seconds that a preflight response can be cached without sending another preflight request</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>CONNECT, DELETE, GET, OPTIONS, PATCH, POST, PUT, TRACE</p></div></div></td><td><div><div><p>Allowed HTTP methods</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Method name</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName.isAllowed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A boolean indicating if a method is allowed</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>HTTP headers used for preflight requests</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.exposedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Headers that browser JavaScript is allowed to access</p></div></div></td></tr><tr><td><div><div><p><code>publicResource</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A boolean indicating if the CORS configuration is to be applied as a public resource</p></div></div></td></tr><tr><td><div><div><p><code>supportCredentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>A boolean indicating if the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: cors-flex config: publicResource: false supportCredentials: true originGroups: -
origins: - http://www.the-origin-of-time.com accessControlMaxAge: 30 allowedMethods: - isAllowed:
true methodName: POST - isAllowed: true methodName: PUT - isAllowed: true methodName: GET -
isAllowed: false methodName: CONNECT - isAllowed: false methodName: DELETE - isAllowed: false
methodName: OPTIONS - isAllowed: false methodName: PATCH - isAllowed: false methodName: TRACE
headers: - x-allow-origin - x-yet-another-valid-header exposedHeaders: - x-forwarded-for

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Public resource</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied as a public resource (default)</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default group</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied only to specific resources (requires unselecting <strong>Public resource</strong>)</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Support credentials</p></div></div></td><td><div><div><p>Whether the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## Why CORS

CORS enables you to achieve web page security and web integrity in your environment. To know why you
might need to apply the CORS policy to your backend, you must first understand _origins_, _cookies_,
and how they can be manipulated to violate web page integrity.

### Introduction to the Web Origin Concept

Origin is a header that specifies the request that initiated the fetch. The origin header includes
only the server name (no path information). At a very basic level, an origin consists of:

- URI scheme: `http://`

- Host name: `www.example.com`

- Port number: `8080`

For requests between any two [origin](#origins) to be approved, the origins must be equal. Origins
are considered equal only if all these three parameters match. For more information, see
[RFC 6454 - The Web Origin Concept](https://tools.ietf.org/html/rfc6454).

### HTTP Cookies

Websites use HTTP cookies to retain stateful information. Most commonly, web servers use
authentication cookies to know whether a user is logged in, and to know which account users are
logged in to. For more information, see [RFC 6265](https://www.ietf.org/rfc/rfc6265.txt).

SOP (same-origin policy) deters malicious attackers from exploiting cookies when one web page
invokes another. For example, you might log in to your bank’s web page using a cookie that an
attacker might be able to obtain and exploit to query the bank’s API on your behalf.

With the SOP, scripts can access data from a target web page only if it has the same origin as the
caller web page. For more information about origins, see
[Wikipedia](https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules).

Because the SOP is highly restrictive, access from one suborigin to another or to external
hyperlinks do not work on web pages. For example, if an origin `www.testapply.com` has two
suborigins, `www.eng.testapply.com` and `www.docs.testapply.com`, communication between the two
suborigins is denied. Additionally, any hyperlinks to external websites from any of the suborigins
is also denied.

To circumvent this problem, web browsers implemented the CORS standard, which validates the web
server and accepts the request if the validation is successful.

For example, if your bank implements the CORS server-side protocol on its login server, you can
query data only directly from the bank’s web page. Any attempt to query the login API from an
external (non-bank) domain is denied.

## How CORS Works

When your web pages request data, the browser detects whether the request is from within same origin
and determines whether to apply the CORS algorithm. If you query data from a web page that is not in
your origin, then the CORS policy is applied.

The CORS algorithm works on the web server and on the client-side for the web page that requested
the information. The client-side algorithm in the CORS policy is implemented by:

- Determining whether the request is complex (and potentially dangerous) and sending a preliminary
  _preflight_ request to verify whether the server accepts the origin.

- Executing the actual request and validating that the server responds correctly and accepts the
  origin.

A _preflight_ is a preliminary request (using OPTIONS as the HTTP method) from the web browser to
the backend server to test the identity (origin and a few other headers) of the web page that is
trying to perform the request.

If the backend does not accept the origin, the backend server responds to the request without a
specific header (Access-Control-Allow-Origin). The client then understands that the page’s origin is
not allowed in that server and does not execute the actual request.

The following diagram shows the XMLHttpRequest (XHR) in a JavaScript flow for determining whether to
execute the actual request:

![A flowchart illustrating the process of standard latency and added latency for Javascript cross-domain XHR calls](/mulesoft/current/en-us/gateway/1.13/_images/cors-policy-xhr-diagram.png)

As illustrated in the diagram, the request is validated based on the communication between the
browser and the server:

- If the request is considered to be complex (see the previous client-side diagram for XHR), then a
  preflight request is executed.

  If the server does not return the proper CORS response headers for the preflight, the client
  library (XHR in the previous example) is not allowed to perform the actual request.

- If the preflight response is correct and complete, then the client library executes the actual
  request, which includes certain CORS headers.

  The client library then validates the CORS headers of the response. If some of the required
  headers are missing, then again the client library is obliged to block the response from reaching
  the client, which is usually a web page.

## CORS Components

You can configure various components of the CORS policy, such as request headers, response headers,
public resources and groups, ordering, and wildcards.

### CORS Request Headers

- Origin: The origin making the cross origin request.

- Access-Control-Request-Method: The method that is invoked in the actual request.

  This header is sent in the preflight request.

- Access-Control-Request-Headers: Custom headers that are sent in the actual request.

  This header is sent in the preflight request. For the GET or HEAD methods, the standard defines a
  specific list of headers that are considered simple enough to not require a preflight. For custom
  headers, a preflight is executed for GET and HEAD requests (see the previous XHR example to
  validate the path in which the client does not have to perform a preflight).

### CORS Response Headers

The headers included in a response depend on whether the request is a preflight or an actual
request:

- `Access-Control-Allow-Origin`: Obligatory in every response.

  If this header is not present in the response, the browser or client library blocks the response
  from reaching the web page. The wildcard “\*” can be used to represent any origin.

- `Access-Control-Allow-Methods`: Allowed methods that can be executed.

  This header is returned in the OPTIONS request (preflight). The server might respond with a list
  of allowed methods, delegating the validation task to the client.

- `Access-Control-Allow-Headers`: Allowed headers in the actual request.

  This header works in a manner similar to how Access-Control-Allow-Methods works .

- `Access-Control-Allow-Credentials`: Notifies the client whether the actual request can be made
  with a cookie.

  The `Access-Control-Allow-Credentials` returns a Boolean value.

- `Access-Control-Expose-Headers`: Provides the browser or client library with a list of headers
  that can be accessed by the web page that executed the request.

  The HTTP library performing the CORS request exposes only the headers to the web page, providing
  further privacy and security.

- `Access-Control-Max-Age`: Specifies the duration (in seconds) in which the browser can avoid
  performing a second preflight on a request.

### Public Resources and Groups

If you need to bypass the browser SOP, Mulesoft provides you an option to configure a public
resource that enables the API gateway policy to mirror the preflight data in the response. This
ensures that the actual request is correctly updated with all the CORS headers so that the browser
accepts the response.

If the public resource option is not secure enough for your environment, define multiple groups for
the different origins that query your API. Each group applies to a list of origins and can specify
different methods, headers, preflight caching time, and expose headers.

### Ordering

The CORS policy is always applied first by the API gateway, before any other policies can be
applied. If a protected request using OPTIONS is sent to an application that has the CORS policy
applied, the request does not reach the protected resource. According to the
[CORS specification](https://fetch.spec.whatwg.org/#resource-preflight-requests), all OPTIONS
requests are considered preflight.

### Configuration Wildcards

Wildcards (`*`) are accepted in the Origins and Headers sections of a group configuration. Use
wildcards when you need a public resource, but must restrict the accepted HTTP methods.

If you have configured multiple groups and one of the groups uses a wildcard origin, the
non-wildcard settings override the wildcard configurations.

## FAQs

**The CORS policy does not seem to be applied.**

If you use tools such as curl or Postman to test the CORS policy for a complex request, the CORS
request headers are not added and the preflight does not occur.

If no CORS headers are sent or improper headers are used in the request, the API gateway CORS policy
does not add any CORS response headers, giving the impression that the policy is not applied. Ensure
that you use the libraries that implement the CORS protocol specific to your environment, or review
the specification to ensure that you are configuring the correct headers.

<!-- document id=e69ef724821adf6b0be579b624add6c75f37348252e7b5d435eb3f2e759ef7fb url=/mulesoft/current/en-us/gateway/1.9/policies-included-cors.md -->

---
product: Omni Gateway
version: 1.9
keywords: cross origin resource sharing, cors, api gateway, flex gateway, gateway, policy
---

# Cross-Origin Resource Sharing (CORS) Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Cross-Origin Resource Sharing (CORS)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables access to resources residing in external domains</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Compliance</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy</p></div></div></td></tr></tbody></table>

## Summary

CORS is a mechanism by which a web application can access resources that are defined in another
domain. Browsers implement this standard by default. The CORS policy complies with the
[CORS W3C recommendation](https://fetch.spec.whatwg.org/) standards.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: cors-flex config: originGroups: <array> // OPTIONAL, default: \[\] - origins:
accessControlMaxAge: allowedMethods: methodName: - isAllowed: headers: <array> // OPTIONAL, default:
\[\] exposedHeaders: <array> // OPTIONAL, default: \[\] publicResource: <bool> // OPTIONAL, default:
true supportCredentials: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>originGroups</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List containing groups of origins</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of origins to be included in the group. For example, <code>http://www.the-origin-of-time.com</code></p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.accessControlMaxAge</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>30</p></div></div></td><td><div><div><p>Duration in seconds that a preflight response can be cached without sending another preflight request</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>CONNECT, DELETE, GET, OPTIONS, PATCH, POST, PUT, TRACE</p></div></div></td><td><div><div><p>Allowed HTTP methods</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Method name</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName.isAllowed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A boolean indicating if a method is allowed</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>HTTP headers used for preflight requests</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.exposedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Headers that browser JavaScript is allowed to access</p></div></div></td></tr><tr><td><div><div><p><code>publicResource</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A boolean indicating if the CORS configuration is to be applied as a public resource</p></div></div></td></tr><tr><td><div><div><p><code>supportCredentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>A boolean indicating if the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: cors-flex config: publicResource: false supportCredentials: true originGroups: -
origins: - http://www.the-origin-of-time.com accessControlMaxAge: 30 allowedMethods: - isAllowed:
true methodName: POST - isAllowed: true methodName: PUT - isAllowed: true methodName: GET -
isAllowed: false methodName: CONNECT - isAllowed: false methodName: DELETE - isAllowed: false
methodName: OPTIONS - isAllowed: false methodName: PATCH - isAllowed: false methodName: TRACE
headers: - x-allow-origin - x-yet-another-valid-header exposedHeaders: - x-forwarded-for

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Public resource</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied as a public resource (default)</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default group</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied only to specific resources (requires unselecting <strong>Public resource</strong>)</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Support credentials</p></div></div></td><td><div><div><p>Whether the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## Why CORS

CORS enables you to achieve web page security and web integrity in your environment. To know why you
might need to apply the CORS policy to your backend, you must first understand _origins_, _cookies_,
and how they can be manipulated to violate web page integrity.

### Introduction to the Web Origin Concept

Origin is a header that specifies the request that initiated the fetch. The origin header includes
only the server name (no path information). At a very basic level, an origin consists of:

- URI scheme: `http://`

- Host name: `www.example.com`

- Port number: `8080`

For requests between any two [origin](#origins) to be approved, the origins must be equal. Origins
are considered equal only if all these three parameters match. For more information, see
[RFC 6454 - The Web Origin Concept](https://datatracker.ietf.org/doc/html/rfc6454).

### HTTP Cookies

Websites use HTTP cookies to retain stateful information. Most commonly, web servers use
authentication cookies to know whether a user is logged in, and to know which account users are
logged in to. For more information, see [RFC 6265](https://www.ietf.org/rfc/rfc6265.txt).

SOP (same-origin policy) deters malicious attackers from exploiting cookies when one web page
invokes another. For example, you might log in to your bank’s web page using a cookie that an
attacker might be able to obtain and exploit to query the bank’s API on your behalf.

With the SOP, scripts can access data from a target web page only if it has the same origin as the
caller web page. For more information about origins, see
[Wikipedia](https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules).

Because the SOP is highly restrictive, access from one suborigin to another or to external
hyperlinks do not work on web pages. For example, if an origin `www.testapply.com` has two
suborigins, `www.eng.testapply.com` and `www.docs.testapply.com`, communication between the two
suborigins is denied. Additionally, any hyperlinks to external websites from any of the suborigins
is also denied.

To circumvent this problem, web browsers implemented the CORS standard, which validates the web
server and accepts the request if the validation is successful.

For example, if your bank implements the CORS server-side protocol on its login server, you can
query data only directly from the bank’s web page. Any attempt to query the login API from an
external (non-bank) domain is denied.

## How CORS Works

When your web pages request data, the browser detects whether the request is from within same origin
and determines whether to apply the CORS algorithm. If you query data from a web page that is not in
your origin, then the CORS policy is applied.

The CORS algorithm works on the web server and on the client-side for the web page that requested
the information. The client-side algorithm in the CORS policy is implemented by:

- Determining whether the request is complex (and potentially dangerous) and sending a preliminary
  _preflight_ request to verify whether the server accepts the origin.

- Executing the actual request and validating that the server responds correctly and accepts the
  origin.

A _preflight_ is a preliminary request (using OPTIONS as the HTTP method) from the web browser to
the backend server to test the identity (origin and a few other headers) of the web page that is
trying to perform the request.

If the backend does not accept the origin, the backend server responds to the request without a
specific header (Access-Control-Allow-Origin). The client then understands that the page’s origin is
not allowed in that server and does not execute the actual request.

The following diagram shows the XMLHttpRequest (XHR) in a JavaScript flow for determining whether to
execute the actual request:

![A flowchart illustrating the process of standard latency and added latency for Javascript cross-domain XHR calls](/mulesoft/current/en-us/gateway/1.9/_images/cors-policy-xhr-diagram.png)

As illustrated in the diagram, the request is validated based on the communication between the
browser and the server:

- If the request is considered to be complex (see the previous client-side diagram for XHR), then a
  preflight request is executed.

  If the server does not return the proper CORS response headers for the preflight, the client
  library (XHR in the previous example) is not allowed to perform the actual request.

- If the preflight response is correct and complete, then the client library executes the actual
  request, which includes certain CORS headers.

  The client library then validates the CORS headers of the response. If some of the required
  headers are missing, then again the client library is obliged to block the response from reaching
  the client, which is usually a web page.

## CORS Components

You can configure various components of the CORS policy, such as request headers, response headers,
public resources and groups, ordering, and wildcards.

### CORS Request Headers

- Origin: The origin making the cross origin request.

- Access-Control-Request-Method: The method that is invoked in the actual request.

  This header is sent in the preflight request.

- Access-Control-Request-Headers: Custom headers that are sent in the actual request.

  This header is sent in the preflight request. For the GET or HEAD methods, the standard defines a
  specific list of headers that are considered simple enough to not require a preflight. For custom
  headers, a preflight is executed for GET and HEAD requests (see the previous XHR example to
  validate the path in which the client does not have to perform a preflight).

### CORS Response Headers

The headers included in a response depend on whether the request is a preflight or an actual
request:

- `Access-Control-Allow-Origin`: Obligatory in every response.

  If this header is not present in the response, the browser or client library blocks the response
  from reaching the web page. The wildcard “\*” can be used to represent any origin.

- `Access-Control-Allow-Methods`: Allowed methods that can be executed.

  This header is returned in the OPTIONS request (preflight). The server might respond with a list
  of allowed methods, delegating the validation task to the client.

- `Access-Control-Allow-Headers`: Allowed headers in the actual request.

  This header works in a manner similar to how Access-Control-Allow-Methods works .

- `Access-Control-Allow-Credentials`: Notifies the client whether the actual request can be made
  with a cookie.

  The `Access-Control-Allow-Credentials` returns a Boolean value.

- `Access-Control-Expose-Headers`: Provides the browser or client library with a list of headers
  that can be accessed by the web page that executed the request.

  The HTTP library performing the CORS request exposes only the headers to the web page, providing
  further privacy and security.

- `Access-Control-Max-Age`: Specifies the duration (in seconds) in which the browser can avoid
  performing a second preflight on a request.

### Public Resources and Groups

If you need to bypass the browser SOP, Mulesoft provides you an option to configure a public
resource that enables the API gateway policy to mirror the preflight data in the response. This
ensures that the actual request is correctly updated with all the CORS headers so that the browser
accepts the response.

If the public resource option is not secure enough for your environment, define multiple groups for
the different origins that query your API. Each group applies to a list of origins and can specify
different methods, headers, preflight caching time, and expose headers.

### Ordering

The CORS policy is always applied first by the API gateway, before any other policies can be
applied. If a protected request using OPTIONS is sent to an application that has the CORS policy
applied, the request does not reach the protected resource. According to the
[CORS specification](https://fetch.spec.whatwg.org/#resource-preflight-requests), all OPTIONS
requests are considered preflight.

### Configuration Wildcards

Wildcards (`*`) are accepted in the Origins and Headers sections of a group configuration. Use
wildcards when you need a public resource, but must restrict the accepted HTTP methods.

If you have configured multiple groups and one of the groups uses a wildcard origin, the
non-wildcard settings override the wildcard configurations.

## FAQs

**The CORS policy does not seem to be applied.**

If you use tools such as curl or Postman to test the CORS policy for a complex request, the CORS
request headers are not added and the preflight does not occur.

If no CORS headers are sent or improper headers are used in the request, the API gateway CORS policy
does not add any CORS response headers, giving the impression that the policy is not applied. Ensure
that you use the libraries that implement the CORS protocol specific to your environment, or review
the specification to ensure that you are configuring the correct headers.

<!-- document id=bfc56910ee903502db8122a1723af516c48e0af9caff5bb12d6ee5a103740ee0 url=/mulesoft/current/en-us/gateway/latest/policies-included-cors.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: cross origin resource sharing, cors, api gateway, flex gateway, gateway, policy
---

# Cross-Origin Resource Sharing (CORS) Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Cross-Origin Resource Sharing (CORS)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables access to resources residing in external domains</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Compliance</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/cors-release-notes">Cross-Origin Resource Sharing (CORS)</a></p></div></div></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy</p></div></div></td></tr></tbody></table>

## Summary

CORS is a mechanism by which a web application can access resources that are defined in another
domain. Browsers implement this standard by default. The CORS policy complies with the
[CORS W3C recommendation](https://fetch.spec.whatwg.org/) standards.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: cors-flex config: originGroups: <array> // OPTIONAL, default: \[\] - origins:
accessControlMaxAge: allowedMethods: methodName: - isAllowed: headers: <array> // OPTIONAL, default:
\[\] exposedHeaders: <array> // OPTIONAL, default: \[\] publicResource: <bool> // OPTIONAL, default:
true supportCredentials: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>originGroups</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List containing groups of origins</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of origins to be included in the group. For example, <code>http://www.the-origin-of-time.com</code></p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.accessControlMaxAge</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>30</p></div></div></td><td><div><div><p>Duration in seconds that a preflight response can be cached without sending another preflight request</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>CONNECT, DELETE, GET, OPTIONS, PATCH, POST, PUT, TRACE</p></div></div></td><td><div><div><p>Allowed HTTP methods</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Method name</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName.isAllowed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A boolean indicating if a method is allowed</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>HTTP headers used for preflight requests</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.exposedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Headers that browser JavaScript is allowed to access</p></div></div></td></tr><tr><td><div><div><p><code>publicResource</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A boolean indicating if the CORS configuration is to be applied as a public resource</p></div></div></td></tr><tr><td><div><div><p><code>supportCredentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>A boolean indicating if the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: cors-flex config: publicResource: false supportCredentials: true originGroups: -
origins: - http://www.the-origin-of-time.com accessControlMaxAge: 30 allowedMethods: - isAllowed:
true methodName: POST - isAllowed: true methodName: PUT - isAllowed: true methodName: GET -
isAllowed: false methodName: CONNECT - isAllowed: false methodName: DELETE - isAllowed: false
methodName: OPTIONS - isAllowed: false methodName: PATCH - isAllowed: false methodName: TRACE
headers: - x-allow-origin - x-yet-another-valid-header exposedHeaders: - x-forwarded-for

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Public resource</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied as a public resource (default)</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default group</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied only to specific resources (requires unselecting <strong>Public resource</strong>)</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Support credentials</p></div></div></td><td><div><div><p>Whether the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## Why CORS

CORS enables you to achieve web page security and web integrity in your environment. To know why you
might need to apply the CORS policy to your backend, you must first understand _origins_, _cookies_,
and how they can be manipulated to violate web page integrity.

### Introduction to the Web Origin Concept

Origin is a header that specifies the request that initiated the fetch. The origin header includes
only the server name (no path information). At a very basic level, an origin consists of:

- URI scheme: `http://`

- Host name: `www.example.com`

- Port number: `8080`

For requests between any two [origin](#origins) to be approved, the origins must be equal. Origins
are considered equal only if all these three parameters match. For more information, see
[RFC 6454 - The Web Origin Concept](https://tools.ietf.org/html/rfc6454).

### HTTP Cookies

Websites use HTTP cookies to retain stateful information. Most commonly, web servers use
authentication cookies to know whether a user is logged in, and to know which account users are
logged in to. For more information, see [RFC 6265](https://www.ietf.org/rfc/rfc6265.txt).

SOP (same-origin policy) deters malicious attackers from exploiting cookies when one web page
invokes another. For example, you might log in to your bank’s web page using a cookie that an
attacker might be able to obtain and exploit to query the bank’s API on your behalf.

With the SOP, scripts can access data from a target web page only if it has the same origin as the
caller web page. For more information about origins, see
[Wikipedia](https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules).

Because the SOP is highly restrictive, access from one suborigin to another or to external
hyperlinks do not work on web pages. For example, if an origin `www.testapply.com` has two
suborigins, `www.eng.testapply.com` and `www.docs.testapply.com`, communication between the two
suborigins is denied. Additionally, any hyperlinks to external websites from any of the suborigins
is also denied.

To circumvent this problem, web browsers implemented the CORS standard, which validates the web
server and accepts the request if the validation is successful.

For example, if your bank implements the CORS server-side protocol on its login server, you can
query data only directly from the bank’s web page. Any attempt to query the login API from an
external (non-bank) domain is denied.

## How CORS Works

When your web pages request data, the browser detects whether the request is from within same origin
and determines whether to apply the CORS algorithm. If you query data from a web page that is not in
your origin, then the CORS policy is applied.

The CORS algorithm works on the web server and on the client-side for the web page that requested
the information. The client-side algorithm in the CORS policy is implemented by:

- Determining whether the request is complex (and potentially dangerous) and sending a preliminary
  _preflight_ request to verify whether the server accepts the origin.

- Executing the actual request and validating that the server responds correctly and accepts the
  origin.

A _preflight_ is a preliminary request (using OPTIONS as the HTTP method) from the web browser to
the backend server to test the identity (origin and a few other headers) of the web page that is
trying to perform the request.

If the backend does not accept the origin, the backend server responds to the request without a
specific header (Access-Control-Allow-Origin). The client then understands that the page’s origin is
not allowed in that server and does not execute the actual request.

The following diagram shows the XMLHttpRequest (XHR) in a JavaScript flow for determining whether to
execute the actual request:

![A flowchart illustrating the process of standard latency and added latency for Javascript cross-domain XHR calls](/mulesoft/current/en-us/gateway/latest/_images/cors-policy-xhr-diagram.png)

As illustrated in the diagram, the request is validated based on the communication between the
browser and the server:

- If the request is considered to be complex (see the previous client-side diagram for XHR), then a
  preflight request is executed.

  If the server does not return the proper CORS response headers for the preflight, the client
  library (XHR in the previous example) is not allowed to perform the actual request.

- If the preflight response is correct and complete, then the client library executes the actual
  request, which includes certain CORS headers.

  The client library then validates the CORS headers of the response. If some of the required
  headers are missing, then again the client library is obliged to block the response from reaching
  the client, which is usually a web page.

## CORS Components

You can configure various components of the CORS policy, such as request headers, response headers,
public resources and groups, ordering, and wildcards.

### CORS Request Headers

- Origin: The origin making the cross origin request.

- Access-Control-Request-Method: The method that is invoked in the actual request.

  This header is sent in the preflight request.

- Access-Control-Request-Headers: Custom headers that are sent in the actual request.

  This header is sent in the preflight request. For the GET or HEAD methods, the standard defines a
  specific list of headers that are considered simple enough to not require a preflight. For custom
  headers, a preflight is executed for GET and HEAD requests (see the previous XHR example to
  validate the path in which the client does not have to perform a preflight).

### CORS Response Headers

The headers included in a response depend on whether the request is a preflight or an actual
request:

- `Access-Control-Allow-Origin`: Obligatory in every response.

  If this header is not present in the response, the browser or client library blocks the response
  from reaching the web page. The wildcard “\*” can be used to represent any origin.

- `Access-Control-Allow-Methods`: Allowed methods that can be executed.

  This header is returned in the OPTIONS request (preflight). The server might respond with a list
  of allowed methods, delegating the validation task to the client.

- `Access-Control-Allow-Headers`: Allowed headers in the actual request.

  This header works in a manner similar to how Access-Control-Allow-Methods works .

- `Access-Control-Allow-Credentials`: Notifies the client whether the actual request can be made
  with a cookie.

  The `Access-Control-Allow-Credentials` returns a Boolean value.

- `Access-Control-Expose-Headers`: Provides the browser or client library with a list of headers
  that can be accessed by the web page that executed the request.

  The HTTP library performing the CORS request exposes only the headers to the web page, providing
  further privacy and security.

- `Access-Control-Max-Age`: Specifies the duration (in seconds) in which the browser can avoid
  performing a second preflight on a request.

### Public Resources and Groups

If you need to bypass the browser SOP, Mulesoft provides you an option to configure a public
resource that enables the API gateway policy to mirror the preflight data in the response. This
ensures that the actual request is correctly updated with all the CORS headers so that the browser
accepts the response.

If the public resource option is not secure enough for your environment, define multiple groups for
the different origins that query your API. Each group applies to a list of origins and can specify
different methods, headers, preflight caching time, and expose headers.

### Ordering

The CORS policy is always applied first by the API gateway, before any other policies can be
applied. If a protected request using OPTIONS is sent to an application that has the CORS policy
applied, the request does not reach the protected resource. According to the
[CORS specification](https://fetch.spec.whatwg.org/#resource-preflight-requests), all OPTIONS
requests are considered preflight.

### Configuration Wildcards

Wildcards (`*`) are accepted in the Origins and Headers sections of a group configuration. Use
wildcards when you need a public resource, but must restrict the accepted HTTP methods.

If you have configured multiple groups and one of the groups uses a wildcard origin, the
non-wildcard settings override the wildcard configurations.

## FAQs

**The CORS policy does not seem to be applied.**

If you use tools such as curl or Postman to test the CORS policy for a complex request, the CORS
request headers are not added and the preflight does not occur.

If no CORS headers are sent or improper headers are used in the request, the API gateway CORS policy
does not add any CORS response headers, giving the impression that the policy is not applied. Ensure
that you use the libraries that implement the CORS protocol specific to your environment, or review
the specification to ensure that you are configuring the correct headers.

<!-- document id=e317956a66ec7fc310dfebf3ccfc612d3b9adb5cc95fe6053208035298a5515e url=/mulesoft/current/en-us/gateway/latest/policies-included-crowdstrike-aidr-guardrails.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, content safety, crowdstrike, falcon, aidr, guardrails, redaction
---

# CrowdStrike AIDR Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>CrowdStrike AIDR Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates OpenAI-format LLM prompts and responses against CrowdStrike Falcon AI Detection and Response (AIDR), rejecting or redacting flagged content</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.14.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/crowdstrike-aidr-guardrails-release-notes">CrowdStrike AIDR Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content rejected by CrowdStrike AIDR</p></td></tr><tr><td><p>503 - Service Unavailable: AIDR call failed, timed out, or returned a verdict the policy can’t use (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The CrowdStrike Falcon AI Detection and Response (AIDR) Guardrails policy provides content
moderation for LLMs by evaluating prompts and responses against
[CrowdStrike Falcon AIDR](https://aidr-docs.crowdstrike.com/). The policy sends the conversation to
AIDR and enforces the returned verdict at the gateway before the request reaches the upstream LLM
(request phase) or before the response is returned to the client (response phase).

The policy supports only OpenAI Chat Completions format traffic, because the AIDR API accepts only
that format.

An AIDR collector token is both the credential and the link to your AIDR policy. Which detectors
run, their thresholds, redaction rules, and whether a detection rejects content are all configured
in the Falcon console, not in the gateway policy. Changes you make in the Falcon console take effect
without needing to modify the gateway policy.

The policy turns each AIDR verdict into one of these gateway actions:

- **Allow**: Content that AIDR doesn’t reject is forwarded unchanged. Detections from an AIDR policy
  in report-only mode are allowed.

- **Redact**: When Enable Transformation is enabled and AIDR returns redacted content, the policy
  replaces the original content with the redacted content and forwards it.

- **Reject**: When AIDR rejects the content, the client receives an HTTP `403` response that names
  the triggered detectors.

The policy rejects content only when the AIDR verdict says to reject it. Detections alone never
cause a rejection.

The policy operates in two independent phases:

- **Request phase**: Sends the prompt messages to AIDR as an input event. Rejected prompts never
  reach the LLM.

- **Response phase**: Sends the LLM completion to AIDR as an output event before returning it to the
  client.

Both phases are enabled by default.

## Before You Begin

Before configuring this policy, you need:

1.  **A CrowdStrike AIDR for Agents subscription.** AIDR for Workforce collectors aren’t supported.

2.  **An AIDR Application collector token**, issued from the Falcon console. The AIDR policy
    assigned to the collector determines how content is evaluated.

3.  **The AIDR endpoint URL for the CrowdStrike cloud that hosts your Falcon tenant.** The cloud is
    the only data residency control AIDR offers, so choose it deliberately. Each URL includes the
    `/aidr/aiguard` path:

    - US-1: `https://api.crowdstrike.com/aidr/aiguard`

    - US-2: `https://api.us-2.crowdstrike.com/aidr/aiguard`

    - EU-1: `https://api.eu-1.crowdstrike.com/aidr/aiguard`

Prompts and responses leave your network when they’re sent to CrowdStrike for evaluation. Ensure the
Omni Gateway can reach the AIDR host outbound. To keep content out of CrowdStrike logs, configure
content logging exclusions in the Falcon console.

Traffic in any other format, non-`POST` requests, and requests without a JSON body pass through
unscanned.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The CrowdStrike AIDR Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>AIDR Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Base URL of the AIDR API for the CrowdStrike cloud that hosts your Falcon tenant: <code>https://api.crowdstrike.com/aidr/aiguard</code> (US-1), <code>https://api.us-2.crowdstrike.com/aidr/aiguard</code> (US-2), or <code>https://api.eu-1.crowdstrike.com/aidr/aiguard</code> (EU-1). Include the <code>/aidr/aiguard</code> path. The policy appends <code>/v1/guard_chat_completions</code> and <code>/v1/unredact</code> at call time.</p></div></div></td></tr><tr><td><div><div><p>Collector Token</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AIDR Application collector token. The token authenticates each call and selects the AIDR policy assigned to the collector. The collector must belong to an AIDR for Agents subscription. This value is sensitive and is never logged.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default), the policy evaluates the prompt messages against AIDR before forwarding them to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default), the policy evaluates the LLM completion against AIDR before returning it to the client.</p></div><div><p>Streaming responses (<code>text/event-stream</code>) are also evaluated. The policy buffers the entire stream and holds the response until the evaluation completes. This breaks the streaming experience for the client and increases latency and memory use.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Request Collector Token</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Collector token to use for the request phase, so prompts can use a different AIDR policy. When not set, the policy uses Collector Token.</p></div></div></td></tr><tr><td><div><div><p>Response Collector Token</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Collector token to use for the response phase, so completions can use a different AIDR policy. When not set, the policy uses Collector Token.</p></div></div></td></tr><tr><td><div><div><p>Application ID</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Application identifier sent on every AIDR call. Use it to identify this API on the AIDR Findings page.</p></div></div></td></tr><tr><td><div><div><p>Collector Instance ID</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Identifier that distinguishes gateway instances or environments that share one collector.</p></div></div></td></tr><tr><td><div><div><p>Enable Transformation</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, the policy replaces the original content with the redacted content that AIDR returns. If the redacted content doesn’t match the original messages one for one, the policy doesn’t apply it and handles the call as failed. See <a href="#fail-open-and-fail-closed">Fail Open and Fail Closed</a>. Default: disabled.</p></div></div></td></tr><tr><td><div><div><p>Enable Unredact</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, the policy restores redacted values in the LLM response, so the LLM never sees the original sensitive values but the client does. Requires Enable Transformation and Moderate Request. See <a href="#redact-and-unredact">Redact and Unredact</a>. Default: disabled.</p></div></div></td></tr><tr><td><div><div><p>Sampling Rate</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Percentage of requests sent to AIDR for evaluation. Must be between <code>0</code> and <code>100</code>. At <code>100</code>, every request is evaluated. Use a lower value to limit AIDR usage. Default: <code>100</code>.</p></div></div></td></tr><tr><td><div><div><p>History Depth</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum number of prior conversation turns sent to AIDR on each call. <code>0</code> sends the full conversation. AIDR rejects payloads larger than 1 MiB, so set a limit if your clients send long conversations. Default: <code>0</code>.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Timeout for each AIDR call in milliseconds. Must be between <code>1000</code> and <code>30000</code>. When Enable Unredact is enabled, the response phase makes two calls, so it can take up to twice this value. Default: <code>5000</code>.</p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when an AIDR call fails, times out, or returns a verdict the policy can’t use:</p></div><div><ul><li><p>Disabled (default): Rejects with HTTP <code>503</code>.</p></li><li><p>Enabled: Allows traffic to proceed unscanned (fail-open mode).</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The CrowdStrike AIDR Guardrails policy integrates with CrowdStrike Falcon AIDR to evaluate LLM
prompts and responses.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when Moderate Request is enabled):

    1.  The policy checks that the request is a `POST` request in OpenAI format with a JSON body.
        Other traffic passes through unscanned.

    2.  The policy decides whether to sample the request, based on Sampling Rate. Requests that
        aren’t sampled are allowed without evaluation in both phases.

    3.  The policy sends the prompt messages, limited by History Depth, to AIDR as an input event,
        with Application ID and Collector Instance ID.

    4.  The policy enforces the AIDR verdict. If the prompt is allowed, the policy forwards it to
        the upstream LLM. If AIDR redacts the prompt and Enable Transformation is enabled, the
        policy forwards the redacted prompt. If AIDR rejects the prompt, the policy returns HTTP
        `403`.

2.  **Response Phase** (when Moderate Response is enabled):

    1.  The policy buffers the LLM response. For a streaming response, the policy rebuilds the full
        completion from the stream.

    2.  The policy sends the completion to AIDR as an output event.

    3.  The policy enforces the AIDR verdict. If the completion is allowed, the policy returns it
        unchanged, or with redacted values restored when Enable Unredact is enabled. If AIDR redacts
        the completion and Enable Transformation is enabled, the policy returns the redacted
        completion. If AIDR rejects the completion, the policy replaces the response with an HTTP
        `403` response.

        > [!NOTE] For streaming responses, the policy can’t apply redacted content or restore
        > redacted values. If AIDR redacts a streaming response, the policy handles the call as
        > failed. See [Fail Open and Fail Closed](#fail-open-and-fail-closed).

### Redact and Unredact

When Enable Transformation and Enable Unredact are both enabled, the policy can keep sensitive
values from the LLM while still returning them to the client:

1.  In the request phase, AIDR redacts sensitive values in the prompt, and the policy forwards the
    redacted prompt to the LLM.

2.  In the response phase, the policy asks AIDR to restore the redacted values in the LLM completion
    before returning it to the client.

Only reversible redaction configured in the Falcon console (format-preserving encryption) can be
restored. Values replaced with a placeholder, for example, `<US_SSN>`, can’t be restored.

The response phase restores values only when AIDR allows the completion. If AIDR redacts the
completion, the client receives the redacted completion.

If restoring values fails, Fail Open determines the result. When Fail Open is disabled, the policy
returns HTTP `503`. When Fail Open is enabled, the client receives the redacted completion.

### Fail Open and Fail Closed

The policy handles these conditions as a failed call:

- The AIDR call returns an error or times out.

- AIDR returns a verdict that doesn’t say whether to reject the content.

- AIDR returns redacted content that the policy can’t apply to the original messages, or to a
  streaming response.

When Fail Open is disabled, the policy rejects the request or response with HTTP `503`. When Fail
Open is enabled, the policy allows the traffic unscanned.

## Example Configurations

The following examples demonstrate common configuration patterns for the CrowdStrike AIDR Guardrails
policy.

### Minimal Configuration

Only the two required fields. Both phases are evaluated, every request is sampled, and failed calls
are rejected with a `5000` ms timeout.

```yaml
- policyRef:
    name: crowdstrike-aidr-guardrails-policy-v1-0-impl
    namespace: default
  config:
    aidrEndpoint: https://api.crowdstrike.com/aidr/aiguard
    collectorToken: "${CROWDSTRIKE_AIDR_COLLECTOR_TOKEN}"
```

### Regional Endpoint, Per-Phase Collectors, and Attribution

An EU-1 endpoint, separate collectors for prompts and completions, and application and instance
identifiers for the AIDR Findings page.

```yaml
- policyRef:
    name: crowdstrike-aidr-guardrails-policy-v1-0-impl
    namespace: default
  config:
    aidrEndpoint: https://api.eu-1.crowdstrike.com/aidr/aiguard
    collectorToken: "${CROWDSTRIKE_AIDR_COLLECTOR_TOKEN}"
    advancedConfiguration:
      requestCollectorToken: "${CROWDSTRIKE_AIDR_INPUT_TOKEN}"
      responseCollectorToken: "${CROWDSTRIKE_AIDR_OUTPUT_TOKEN}"
      applicationId: checkout-assistant
      collectorInstanceId: gateway-prod-eu
      apiTimeoutMs: 8000
```

### Redact and Unredact With Sampling

Redacts sensitive values before the prompt reaches the LLM, restores them in the response to the
client, and evaluates 25% of requests to limit AIDR usage.

```yaml
- policyRef:
    name: crowdstrike-aidr-guardrails-policy-v1-0-impl
    namespace: default
  config:
    aidrEndpoint: https://api.crowdstrike.com/aidr/aiguard
    collectorToken: "${CROWDSTRIKE_AIDR_COLLECTOR_TOKEN}"
    advancedConfiguration:
      enableTransformation: true
      enableUnredact: true
      samplingRate: 25
```

### Request-Only, Fail-Open, Limited History

Only the prompt is evaluated, only the last 10 conversation turns are sent to AIDR, and if AIDR is
unreachable the request proceeds unscanned.

```yaml
- policyRef:
    name: crowdstrike-aidr-guardrails-policy-v1-0-impl
    namespace: default
  config:
    aidrEndpoint: https://api.us-2.crowdstrike.com/aidr/aiguard
    collectorToken: "${CROWDSTRIKE_AIDR_COLLECTOR_TOKEN}"
    moderateRequest: true
    moderateResponse: false
    advancedConfiguration:
      historyDepth: 10
      failOpen: true
```

## See Also

- [CrowdStrike AIDR documentation](https://aidr-docs.crowdstrike.com/)

- [Azure Content Safety Policy](https://docs.mulesoft.com/gateway/latest/policies-included-azure-content-safety)

- [Amazon Bedrock Guardrails Policy](https://docs.mulesoft.com/gateway/latest/policies-included-bedrock-guardrails)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies)

<!-- document id=ac00453e822c0f2ce2917b7d0537a2d724a972f9689de3115cb0aa475f7d11f1 url=/mulesoft/current/en-us/gateway/1.12/policies-custom-overview.md -->

---
product: Omni Gateway
version: 1.12
---

# Custom Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Policies enforce regulations to help manage security, control traffic, and improve API adoption. For
example, a policy can control authentication, access, and service level agreements (SLAs). You can
create custom policies based on your specific business requirements and apply them to APIs to extend
existing functionality or define new ones.

The workflow for creating custom policies for Anypoint Flex Gateway is done in Exchange. The policy
is then available to be applied to an API in Anypoint API Manager.

For more information, refer to the following:

- [Implement a Flex Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.12/policies-custom-flex-implement-rust)

- [Publish a Flex Gateway Custom Policy](https://docs.mulesoft.com/gateway/1.12/policies-custom-flex-getting-started)

- [Apply a Flex Gateway Custom Policy in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-deploy-custom-policy)

<!-- document id=8b4563bee5563c171e593bc8673cfd7703c9c39017277ace438947fc48864509 url=/mulesoft/current/en-us/gateway/1.13/policies-custom-overview.md -->

---
product: Omni Gateway
version: 1.13
---

# Custom Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Policies enforce regulations to help manage security, control traffic, and improve API adoption. For
example, a policy can control authentication, access, and service level agreements (SLAs). You can
create custom policies based on your specific business requirements and apply them to APIs to extend
existing functionality or define new ones.

The workflow for creating custom policies for Omni Gateway is done in Exchange. The policy is then
available to be applied to an API in Anypoint API Manager.

For more information, refer to the following:

- [Implement an Omni Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.13/policies-custom-implement-rust)

- [Publish an Omni Gateway Custom Policy](https://docs.mulesoft.com/gateway/1.13/policies-custom-getting-started)

- [Apply an Omni Gateway Custom Policy in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-deploy-custom-policy)

<!-- document id=1b47e89850c8b0f60cc082c43c072a80b9e9ad8d1afa967ba9573b5b7a15ea9a url=/mulesoft/current/en-us/gateway/1.9/policies-custom-overview.md -->

---
product: Omni Gateway
version: 1.9
---

# Custom Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Policies enforce regulations to help manage security, control traffic, and improve API adoption. For
example, a policy can control authentication, access, and service level agreements (SLAs). You can
create custom policies based on your specific business requirements and apply them to APIs to extend
existing functionality or define new ones.

The workflow for creating custom policies for Anypoint Flex Gateway is done in Exchange. The policy
is then available to be applied to an API in Anypoint API Manager.

For more information, refer to the following:

- [Implement a Flex Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.9/policies-custom-flex-implement-rust)

- [Publish a Flex Gateway Custom Policy](https://docs.mulesoft.com/gateway/1.9/policies-custom-flex-getting-started)

- [Apply a Flex Gateway Custom Policy in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-deploy-custom-policy)

<!-- document id=96214adf2e6512ae6fc38361bea7b3220bb36eab048f652682c83d9a4f2f3c53 url=/mulesoft/current/en-us/gateway/latest/policies-custom-overview.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Custom Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Policies enforce regulations to help manage security, control traffic, and improve API adoption. For
example, a policy can control authentication, access, and service level agreements (SLAs). You can
create custom policies based on your specific business requirements and apply them to APIs to extend
existing functionality or define new ones.

The workflow for creating custom policies for Omni Gateway is done in Exchange. The policy is then
available to be applied to an API in Anypoint API Manager.

For more information, refer to the following:

- [Implement an Omni Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/latest/policies-custom-implement-rust)

- [Publish an Omni Gateway Custom Policy](https://docs.mulesoft.com/gateway/latest/policies-custom-getting-started)

- [Apply an Omni Gateway Custom Policy in Local Mode](https://docs.mulesoft.com/gateway/latest/local-deploy-custom-policy)

<!-- document id=d037b41e0992ef8ec023fe04c38b01e10ece7523e2a63079cd40bc6b8ca4d2bb url=/mulesoft/current/en-us/gateway/1.12/policies-included-dataweave-body-transformation.md -->

---
product: Omni Gateway
version: 1.12
keywords: dataweave, body transformation, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Body Transformation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Body Transformation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transforms the body of request or response traffic with a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Body Transformation policy transforms request or response body content with a
DataWeave script. The script receives `attributes.headers` and `payload`. The gateway streams body
processing. If the script declares an output MIME type, such as `output application/json`, the
gateway uses it for the transformed response. Otherwise, the gateway keeps the original
`Content-Type`. In the request or response, the gateway processes the body in streaming mode and
updates `Content-Type` and `Content-Length` after transformation.

## Configure Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: dataweave-body-transformation-flex config: script: <string> // REQUIRED -
DataWeave script requestFlow: <string> // REQUIRED - "onRequest" or "onResponse"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that transforms the body. The script receives <code>attributes.headers</code> and <code>payload</code>. Declare the output MIME type in the script when needed, such as <code>output application/json</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requestFlow</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body. Supported values: <code>onRequest</code> or <code>onResponse</code>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

This example transforms the request payload to a new structure that includes the value from the
custom header `custom-client-header` and fields from the payload:

policies: - policyRef: name: dataweave-body-transformation-flex config: script: | { "id":
attributes.headers.'custom-client-header', "username": payload.name ++ payload.surname }

To transform the response body and set a custom output format such as XML, declare the output and
use `requestFlow: onResponse`:

policies: - policyRef: name: dataweave-body-transformation-flex config: script: | output
application/xml --- { "trace": payload.headers.'X-Amzn-Trace-Id', "custom-data": "custom-value" }
requestFlow: onResponse

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Body Transformation</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that transforms the body</p></div></div></td></tr><tr><td><div><div><p>Request flow</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body</p></div></div></td></tr></tbody></table>

<!-- document id=4174c8d4685e38d12e9efb79868fa531138506a00adf09f52228457f7262ed94 url=/mulesoft/current/en-us/gateway/1.13/policies-included-dataweave-body-transformation.md -->

---
product: Omni Gateway
version: 1.13
keywords: dataweave, body transformation, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Body Transformation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Body Transformation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transforms the body of request or response traffic with a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-body-transformation-release-notes">DataWeave Body Transformation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Body Transformation policy transforms request or response body content with a
DataWeave script. The script receives `attributes.headers` and `payload`. The gateway streams body
processing. If the script declares an output MIME type, such as `output application/json`, the
gateway uses it for the transformed response. Otherwise, the gateway keeps the original
`Content-Type`. In the request or response, the gateway processes the body in streaming mode and
updates `Content-Type` and `Content-Length` after transformation.

## Configure Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: dataweave-body-transformation-flex config: script: <string> // REQUIRED -
DataWeave script requestFlow: <string> // REQUIRED - "onRequest" or "onResponse"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that transforms the body. The script receives <code>attributes.headers</code> and <code>payload</code>. Declare the output MIME type in the script when needed, such as <code>output application/json</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requestFlow</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body. Supported values: <code>onRequest</code> or <code>onResponse</code>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

This example transforms the request payload to a new structure that includes the value from the
custom header `custom-client-header` and fields from the payload:

policies: - policyRef: name: dataweave-body-transformation-flex config: script: | { "id":
attributes.headers.'custom-client-header', "username": payload.name ++ payload.surname }

To transform the response body and set a custom output format such as XML, declare the output and
use `requestFlow: onResponse`:

policies: - policyRef: name: dataweave-body-transformation-flex config: script: | output
application/xml --- { "trace": payload.headers.'X-Amzn-Trace-Id', "custom-data": "custom-value" }
requestFlow: onResponse

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Body Transformation</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that transforms the body</p></div></div></td></tr><tr><td><div><div><p>Request flow</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body</p></div></div></td></tr></tbody></table>

<!-- document id=c63d9ab10e67c5f060d7c1cf9b0590418c1b92f7c1f26949c5d80014ab784ff6 url=/mulesoft/current/en-us/gateway/latest/policies-included-dataweave-body-transformation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: dataweave, body transformation, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Body Transformation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Body Transformation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transforms the body of request or response traffic with a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-body-transformation-release-notes">DataWeave Body Transformation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Body Transformation policy transforms request or response body content with a
DataWeave script. The script receives `attributes.headers` and `payload`. The gateway streams body
processing. If the script declares an output MIME type, such as `output application/json`, the
gateway uses it for the transformed response. Otherwise, the gateway keeps the original
`Content-Type`. In the request or response, the gateway processes the body in streaming mode and
updates `Content-Type` and `Content-Length` after transformation.

## Configure Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: dataweave-body-transformation-flex config: script: <string> // REQUIRED -
DataWeave script requestFlow: <string> // REQUIRED - "onRequest" or "onResponse"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that transforms the body. The script receives <code>attributes.headers</code> and <code>payload</code>. Declare the output MIME type in the script when needed, such as <code>output application/json</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requestFlow</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body. Supported values: <code>onRequest</code> or <code>onResponse</code>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

This example transforms the request payload to a new structure that includes the value from the
custom header `custom-client-header` and fields from the payload:

policies: - policyRef: name: dataweave-body-transformation-flex config: script: | { "id":
attributes.headers.'custom-client-header', "username": payload.name ++ payload.surname }

To transform the response body and set a custom output format such as XML, declare the output and
use `requestFlow: onResponse`:

policies: - policyRef: name: dataweave-body-transformation-flex config: script: | output
application/xml --- { "trace": payload.headers.'X-Amzn-Trace-Id', "custom-data": "custom-value" }
requestFlow: onResponse

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Body Transformation</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that transforms the body</p></div></div></td></tr><tr><td><div><div><p>Request flow</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body</p></div></div></td></tr></tbody></table>

<!-- document id=5186748f60c81fd054a3867b213d932e23ce813b9f75866ba0af59860f3b0336 url=/mulesoft/current/en-us/gateway/1.12/policies-included-dataweave-headers-transformation.md -->

---
product: Omni Gateway
version: 1.12
keywords: dataweave, headers transformation, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Headers Transformation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Headers Transformation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transforms headers of request or response traffic with a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Headers Transformation policy transforms request or response headers with a DataWeave
script. The script receives headers and the message body, and returns a map of header names to
values. In the request or response, the gateway removes existing headers and runs the script with
header bindings. The script output must be a map. Each entry becomes a header. For multi-value
headers, use a list of values.

## Configure Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: dataweave-headers-transformation-flex config: script: <string> // REQUIRED -
DataWeave script requestFlow: <string> // REQUIRED - "onRequest" or "onResponse" requiresPayload:
<boolean> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that returns a map of header names to values. The script receives <code>attributes.headers</code>. If <code>requiresPayload</code> is true, the script also receives the message body in the <code>payload</code> binding.</p></div></div></td></tr><tr><td><div><div><p><code>requestFlow</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body. Supported values: <code>onRequest</code> or <code>onResponse</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requiresPayload</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the script receives the message body in the <code>payload</code> binding. The gateway buffers the body for the transformation.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

This example adds custom headers with conditional logic. When the header `custom-client-header` is
set to `fixed_client`, the gateway replaces it with `custom-123123231231231231`. Otherwise, the
gateway uses the header value or `client-id-not-set`:

policies: - policyRef: name: dataweave-headers-transformation-flex config: script: | {
"custom\_client\_secret": "fixed\_secret\_123123231231231231", "custom\_client\_id": if
(attributes.headers.'custom-client-header'?) attributes.headers.'custom-client-header' match { case
literalMatch: "fixed\_client" -> "custom-123123231231231231" else ->
attributes.headers.'custom-client-header' } else "client-id-not-set" }

To append custom headers using payload data, for example to add the payload `id` to a custom header,
set `requiresPayload: true` and include `payload` in the script:

policies: - policyRef: name: dataweave-headers-transformation-flex config: script: |
attributes.headers ++ { "custom\_client\_id\_from\_payload": payload.id,
"custom\_client\_secret\_from\_payload": payload.secret } requiresPayload: true

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Headers Transformation</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that returns a map of headers</p></div></div></td></tr><tr><td><div><div><p>Request flow</p></div></div></td><td><div><div><p>The flow where the policy applies: request or response</p></div></div></td></tr><tr><td><div><div><p>Requires payload</p></div></div></td><td><div><div><p>Whether the script requires the message body</p></div></div></td></tr></tbody></table>

<!-- document id=2c61975c992f7f5dd9bd42252aebe23a4af2ada1ad44028c86aa9529542f8dfc url=/mulesoft/current/en-us/gateway/1.13/policies-included-dataweave-headers-transformation.md -->

---
product: Omni Gateway
version: 1.13
keywords: dataweave, headers transformation, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Headers Transformation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Headers Transformation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transforms headers of request or response traffic with a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-headers-transformation-release-notes">DataWeave Headers Transformation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Headers Transformation policy transforms request or response headers with a DataWeave
script. The script receives headers and the message body, and returns a map of header names to
values. In the request or response, the gateway removes existing headers and runs the script with
header bindings. The script output must be a map. Each entry becomes a header. For multi-value
headers, use a list of values.

## Configure Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: dataweave-headers-transformation-flex config: script: <string> // REQUIRED -
DataWeave script requestFlow: <string> // REQUIRED - "onRequest" or "onResponse" requiresPayload:
<boolean> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that returns a map of header names to values. The script receives <code>attributes.headers</code>. If <code>requiresPayload</code> is true, the script also receives the message body in the <code>payload</code> binding.</p></div></div></td></tr><tr><td><div><div><p><code>requestFlow</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body. Supported values: <code>onRequest</code> or <code>onResponse</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requiresPayload</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the script receives the message body in the <code>payload</code> binding. The gateway buffers the body for the transformation.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

This example adds custom headers with conditional logic. When the header `custom-client-header` is
set to `fixed_client`, the gateway replaces it with `custom-123123231231231231`. Otherwise, the
gateway uses the header value or `client-id-not-set`:

policies: - policyRef: name: dataweave-headers-transformation-flex config: script: | {
"custom\_client\_secret": "fixed\_secret\_123123231231231231", "custom\_client\_id": if
(attributes.headers.'custom-client-header'?) attributes.headers.'custom-client-header' match { case
literalMatch: "fixed\_client" -> "custom-123123231231231231" else ->
attributes.headers.'custom-client-header' } else "client-id-not-set" }

To append custom headers using payload data, for example to add the payload `id` to a custom header,
set `requiresPayload: true` and include `payload` in the script:

policies: - policyRef: name: dataweave-headers-transformation-flex config: script: |
attributes.headers ++ { "custom\_client\_id\_from\_payload": payload.id,
"custom\_client\_secret\_from\_payload": payload.secret } requiresPayload: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Headers Transformation</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that returns a map of headers</p></div></div></td></tr><tr><td><div><div><p>Request flow</p></div></div></td><td><div><div><p>The flow where the policy applies: request or response</p></div></div></td></tr><tr><td><div><div><p>Requires payload</p></div></div></td><td><div><div><p>Whether the script requires the message body</p></div></div></td></tr></tbody></table>

<!-- document id=841e6931afd41e3c6e9b318fe4cedfc0c5d593447aab229028f87bef3512d878 url=/mulesoft/current/en-us/gateway/latest/policies-included-dataweave-headers-transformation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: dataweave, headers transformation, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Headers Transformation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Headers Transformation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Transforms headers of request or response traffic with a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-headers-transformation-release-notes">DataWeave Headers Transformation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Headers Transformation policy transforms request or response headers with a DataWeave
script. The script receives headers and the message body, and returns a map of header names to
values. In the request or response, the gateway removes existing headers and runs the script with
header bindings. The script output must be a map. Each entry becomes a header. For multi-value
headers, use a list of values.

## Configure Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: dataweave-headers-transformation-flex config: script: <string> // REQUIRED -
DataWeave script requestFlow: <string> // REQUIRED - "onRequest" or "onResponse" requiresPayload:
<boolean> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that returns a map of header names to values. The script receives <code>attributes.headers</code>. If <code>requiresPayload</code> is true, the script also receives the message body in the <code>payload</code> binding.</p></div></div></td></tr><tr><td><div><div><p><code>requestFlow</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>Whether the policy transforms the request or response body. Supported values: <code>onRequest</code> or <code>onResponse</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requiresPayload</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the script receives the message body in the <code>payload</code> binding. The gateway buffers the body for the transformation.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

This example adds custom headers with conditional logic. When the header `custom-client-header` is
set to `fixed_client`, the gateway replaces it with `custom-123123231231231231`. Otherwise, the
gateway uses the header value or `client-id-not-set`:

policies: - policyRef: name: dataweave-headers-transformation-flex config: script: | {
"custom\_client\_secret": "fixed\_secret\_123123231231231231", "custom\_client\_id": if
(attributes.headers.'custom-client-header'?) attributes.headers.'custom-client-header' match { case
literalMatch: "fixed\_client" -> "custom-123123231231231231" else ->
attributes.headers.'custom-client-header' } else "client-id-not-set" }

To append custom headers using payload data, for example to add the payload `id` to a custom header,
set `requiresPayload: true` and include `payload` in the script:

policies: - policyRef: name: dataweave-headers-transformation-flex config: script: |
attributes.headers ++ { "custom\_client\_id\_from\_payload": payload.id,
"custom\_client\_secret\_from\_payload": payload.secret } requiresPayload: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Headers Transformation</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that returns a map of headers</p></div></div></td></tr><tr><td><div><div><p>Request flow</p></div></div></td><td><div><div><p>The flow where the policy applies: request or response</p></div></div></td></tr><tr><td><div><div><p>Requires payload</p></div></div></td><td><div><div><p>Whether the script requires the message body</p></div></div></td></tr></tbody></table>

<!-- document id=01323efc7293f2c022116581d4f73aa5141c697d7fc1af519a9aee390d131418 url=/mulesoft/current/en-us/gateway/1.12/policies-included-dataweave-request-filter.md -->

---
product: Omni Gateway
version: 1.12
keywords: dataweave, request filter, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Request Filter Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Request Filter</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Filters requests by using a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>1.12</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Request Filter policy evaluates a DataWeave script on the request, including headers
and the body, to allow or block the message. The script returns an object with a Boolean `success`
value. If `success` is `false`, the script can return a `response` object with `statusCode`, `body`,
and `headers`. The gateway sends that as the immediate HTTP response to the client and stops
processing. If `success` is `true`, the message continues.

Result format:

- Success: `{ "success": true }`

- Error: `{ "success": false, "response": { "body": "…​", "headers": {}, "statusCode": 400 } }`

## Configure Policy Parameters

### Flex Gateway Local Mode

\- policyRef: name: dataweave-request-filter-flex config: script: <string> // REQUIRED - DataWeave
script requiresPayload: <boolean> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that returns an object with a boolean <code>success</code> field. If <code>success</code> is <code>false</code>, the optional <code>response</code> is: <code>{ "body": string, "headers": object, "statusCode": number }</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requiresPayload</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the script receives the message body in the <code>payload</code> binding. If true and the body is missing, the gateway returns an error.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

policies: - policyRef: name: dataweave-request-filter-flex config: script: | %dw 2.0 output
application/java --- if (attributes.headers\["x-api-key"\] != null) { success: true } else {
success: false, response: { statusCode: 401, body: "Missing API key", headers: {} } }
requiresPayload: false

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Request Filter</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that returns a success or error result</p></div></div></td></tr><tr><td><div><div><p>Requires payload</p></div></div></td><td><div><div><p>Whether the script requires the message body</p></div></div></td></tr></tbody></table>

<!-- document id=9d81f97a73d3d75f56ada04d0bf3f0bda0c7a20fd0205add42e0baa2d77569eb url=/mulesoft/current/en-us/gateway/1.13/policies-included-dataweave-request-filter.md -->

---
product: Omni Gateway
version: 1.13
keywords: dataweave, request filter, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Request Filter Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Request Filter</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Filters requests by using a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>1.12</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-request-filter-release-notes">DataWeave Request Filter</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Request Filter policy evaluates a DataWeave script on the request, including headers
and the body, to allow or block the message. The script returns an object with a Boolean `success`
value. If `success` is `false`, the script can return a `response` object with `statusCode`, `body`,
and `headers`. The gateway sends that as the immediate HTTP response to the client and stops
processing. If `success` is `true`, the message continues.

Result format:

- Success: `{ "success": true }`

- Error: `{ "success": false, "response": { "body": "…​", "headers": {}, "statusCode": 400 } }`

## Configure Policy Parameters

### Omni Gateway Local Mode

\- policyRef: name: dataweave-request-filter-flex config: script: <string> // REQUIRED - DataWeave
script requiresPayload: <boolean> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that returns an object with a boolean <code>success</code> field. If <code>success</code> is <code>false</code>, the optional <code>response</code> is: <code>{ "body": string, "headers": object, "statusCode": number }</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requiresPayload</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the script receives the message body in the <code>payload</code> binding. If true and the body is missing, the gateway returns an error.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

policies: - policyRef: name: dataweave-request-filter-flex config: script: | %dw 2.0 output
application/java --- if (attributes.headers\["x-api-key"\] != null) { success: true } else {
success: false, response: { statusCode: 401, body: "Missing API key", headers: {} } }
requiresPayload: false

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Request Filter</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that returns a success or error result</p></div></div></td></tr><tr><td><div><div><p>Requires payload</p></div></div></td><td><div><div><p>Whether the script requires the message body</p></div></div></td></tr></tbody></table>

<!-- document id=3b36e31d96a6a543cb5dd3228d7175e55cc3138753be291466202c74945f2111 url=/mulesoft/current/en-us/gateway/latest/policies-included-dataweave-request-filter.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: dataweave, request filter, transformation, api gateway, flex gateway, gateway, policy
---

# DataWeave Request Filter Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>DataWeave Request Filter</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Filters requests by using a DataWeave script</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>1.12</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-request-filter-release-notes">DataWeave Request Filter</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - The DataWeave script failed to execute or returned an invalid result</p></td></tr></tbody></table>

## Summary

The DataWeave Request Filter policy evaluates a DataWeave script on the request, including headers
and the body, to allow or block the message. The script returns an object with a Boolean `success`
value. If `success` is `false`, the script can return a `response` object with `statusCode`, `body`,
and `headers`. The gateway sends that as the immediate HTTP response to the client and stops
processing. If `success` is `true`, the message continues.

Result format:

- Success: `{ "success": true }`

- Error: `{ "success": false, "response": { "body": "…​", "headers": {}, "statusCode": 400 } }`

## Configure Policy Parameters

### Omni Gateway Local Mode

\- policyRef: name: dataweave-request-filter-flex config: script: <string> // REQUIRED - DataWeave
script requiresPayload: <boolean> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>A DataWeave script that returns an object with a boolean <code>success</code> field. If <code>success</code> is <code>false</code>, the optional <code>response</code> is: <code>{ "body": string, "headers": object, "statusCode": number }</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requiresPayload</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the script receives the message body in the <code>payload</code> binding. If true and the body is missing, the gateway returns an error.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

policies: - policyRef: name: dataweave-request-filter-flex config: script: | %dw 2.0 output
application/java --- if (attributes.headers\["x-api-key"\] != null) { success: true } else {
success: false, response: { statusCode: 401, body: "Missing API key", headers: {} } }
requiresPayload: false

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>DataWeave Request Filter</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The DataWeave script that returns a success or error result</p></div></div></td></tr><tr><td><div><div><p>Requires payload</p></div></div></td><td><div><div><p>Whether the script requires the message body</p></div></div></td></tr></tbody></table>

<!-- document id=c3564cc8c998fcb52623a72f1edf1fb2130332ffa72d4e50d25fe31cefda4034 url=/mulesoft/current/en-us/gateway/1.12/policies-flex-dataweave-support.md -->

# DataWeave Support in Flex Gateway Policies

[DataWeave](https://docs.mulesoft.com/dataweave/latest/) is the programming language designed by MuleSoft for data transformation. It enables you to build a simple solution for a common integration developer use case: read and parse data from one format, transform the data, and write it out as a different format.

Flex Gateway supports a subset of DataWeave in policy configuration expressions. DataWeave is only supported in included policies and custom policies created with PDK..

## [](#available-types)Available Types

- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#null)
- `Boolean`
- `String`
- `Number` (Driven as 64 bits floating points)
- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#array-type)
- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#object-type) (Repeated keys are not available)

## [](#available-value-constructors-for-types)Available Value Constructors for Types

- [`Boolean`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_boolean)
- [`String`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_string)
- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_null)
- [`Number`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_number)
- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_array)

## [](#unavailable-value-constructors-for-types)Unavailable Value Constructors for Types

- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_object) (Objects can not be defined as literals)

## [](#available-flow-control-structures)Available Flow Control Structures

- [`if else`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_if_else)

## [](#unavailable-flow-control-structures)Unavailable Flow Control Structures

- [`do`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_do)

## [](#available-selectors)Available Selectors

- `Array[Number]`
- `Array[String]`
- `Object[String]`
- `String[Number]`

## [](#unavailable-selectors)Unavailable Selectors

- `Object[Number]`

## [](#available-equality-and-relational-operators)Available Equality and Relational Operators

- [`==`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`!=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`>=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`<=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)

## [](#available-logical-operators)Available Logical Operators

- [`not`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)
- [`and`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)
- [`or`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)

## [](#available-default-operators)Available Default Operators

- [`default`](https://docs.mulesoft.com/dataweave/latest/dataweave-cookbook-defaults#example-of-using-the-keyword-default-to-set-a-default-value)

## [](#available-functions)Available Functions

### [](#)`++`

- [`++(Array<S>, Array<T>): Array<S | T>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus1)
- [`++(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus2)

### [](#available-minus-operators)`--`

- [`--<S>(source: Array<S>, toRemove: Array<Any>): Array<S>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus1)
- [`--<K, V>(source: { (K)?: V }, toRemove: Object): { (K)?: V }`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus2)
- [`--(source: Object, keys: Array<String>)`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus3)

### [](#contains)`contains`

- [`contains(Array<T>, Any): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains1)
- [`contains(String, String): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains2)

### [](#lower)`lower`

- [`lower(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower1)
- [`lower(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower2)

### [](#splitby)`splitBy`

- [`splitBy(String, String): Array<String>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-splitby#splitby2)

### [](#sizeof)`sizeOf`

- [`sizeOf(Array<Any>): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof1)
- [`sizeOf(Object): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof2)
- [`sizeOf(String): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof4)

### [](#trim)`trim`

- [`trim(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim1)
- [`trim(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim2)

### [](#upper)`upper`

- [`upper(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper1)
- [`upper(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper2)

### [](#uuid)`uuid`

- [`uuid(): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-uuid#uuid1)

### [](#dwcorestringssubstringafter)`dw::core::Strings::substringAfter`

- [`substringAfter(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter1)
- [`substringAfter(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter2)

### [](#dwcorestringssubstringafterlast)`dw::core::Strings::substringAfterLast`

- [`substringAfterLast(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast1)
- [`substringAfterLast(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast2)

### [](#dwcorestringssubstringbefore)`dw::core::Strings::substringBefore`

- [`substringBefore(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore1)
- [`substringBefore(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore2)

### [](#dwcorestringssubstringbeforelast)`dw::core::Strings::substringBeforeLast`

- [`substringBeforeLast(text: String, separator: String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast1)
- [`substringBeforeLast(text: Null, separator: String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast2)

### [](#tobase64)toBase64

- [`toBase64(content: Binary): String`](https://docs.mulesoft.com/dataweave/latest/dw-binaries-functions-tobase64#tobase641)

### [](#frombase64)fromBase64

- [`fromBase64(base64String: String): Binary`](https://docs.mulesoft.com/dataweave/latest/dw-binaries-functions-frombase64#frombase641)

<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Flex Gateway doesn’t support DataWeave expressions with binary type results. To use the <code>dw::Binaries::fromBase64('dXNlcjpwYXNz')</code> function, transform the result to a string. Transform the binary output to a string with the <code>dw::util::Coercions::toString(binary: Binary, encoding: String): String</code> function. For example, <code><mark>[dw::util::Coercions::toString(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), 'UTF-8')]</mark></code>.
If using a different function that transforms the binary by default, such as <code>[splitBy(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), ':')]</code>, you can skip manually transforming the binary.</p>
</div>
</td>
</tr>
</tbody></table>

### [](#tobinary)toBinary

- [`toBinary(str: String, encoding: String): Binary`](https://docs.mulesoft.com/dataweave/latest/dw-coercions-functions-tobinary#tobinary1)

### [](#tostring)toString

- [`toString(binary: Binary, encoding: String): String`](https://docs.mulesoft.com/dataweave/latest/dw-coercions-functions-tostring#tostring3)

## [](#available-predefined-variables)Available Predefined Variables

- [`attributes`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - `attributes.headers`
    - `attributes.method` (Only available in request context)
    - `attributes.queryParams` (Only available in request context)
    - `attributes.queryString` (Only available in request context)
    - `attributes.requestPath` (Only available in request context)
    - `attributes.requestUri` (Only available in request context)
    - `attributes.localAddress` (Only available in request context)
    - `attributes.remoteAddress` (Only available in request context)
    - `attributes.scheme` (Only available in request context)
    - `attributes.version` (Only available in request context)
    - `attributes.statusCode` (Only available in response context)
- [`authentication`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - `authentication.clientId`
    - `authentication.clientName`
    - `authentication.principal`
    - `authentication.properties`
        
        To learn more about how to access the authentication object, see [Access the Authentication Object](#access-authentication-object).
- `payload`
    
    - Fields depend on the current payload. For example, `#[payload]` returns the body of the message.
- [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - Individual policies support different sets of variables. For information, refer to the policies listed in [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory).

## [](#dataweave-usage-examples)DataWeave Usage Examples

You can use DataWeave to extract different values from the request and response.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">The Flex Gateway Policy Development Kit (PDK) provides the <a href="https://github.com/mulesoft/pdk-custom-policy-examples/tree/main/dataweave">DataWeave example policy</a> that you can use to test DataWeave expressions.</td></tr></tbody></table>

For example, use DataWeave expressions to:

- Read a header:
    
    #\[attributes.headers.'my-header'\]
- Ensure a specific header is defined:
    
    #\[attributes.headers.'my-header' != null\]
- Check if a request has basic authorization:
    
    #\[lower(splitBy(attributes.headers.authorization default '', ' ')\[0\]) == 'basic'\]
- Check if a request contains `/some` path:
    
    #\[attributes.requestPath contains '/some'\]
- Check if a request doesn’t contain `/some` path:
    
    #\[not(attributes.requestPath contains '/some')\]
- Read the username from a `Basic` authorization header:
    
    #\[splitBy(dw::core::Binaries::fromBase64(dw::core::Strings::substringAfter(attributes.headers.authorization default '', 'Basic')), ':')\[0\]\]
- Read the password from a `Basic` authorization header:
    
    #\[splitBy(dw::core::Binaries::fromBase64(dw::core::Strings::substringAfter(attributes.headers.authorization default '', 'Basic ')), ':')\[1\]\]
- Read the first value of the `x-forwarded-for` header:
    
    #\[trim(splitBy(attributes.headers.'x-forwarded-for', ',')\[0\])\]
- Read the last value of the `x-forwarded-for` header:
    
    #\[trim(splitBy(attributes.headers.'x-forwarded-for', ',')\[-1\])\]
- Read the value from a `Cookie`:
    
    #\[trim(dw::core::Strings::substringBefore(dw::core::Strings::substringAfter(attributes.headers.Cookie default '', 'myCookieName='), ';'))\]
- Check if a single value or space-separated header contains a specific value:
    
    #\[splitBy(attributes.headers.scopes default '', ' ') contains 'read'\]

## [](#access-authentication-object)Access the Authentication Object

To access the [`authentication`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) object, you must first configure an authentication policy that populates the object.

The authentication policy you apply affects the available authentication object properties:

- Multiple policies can validate Client ID:
    
    - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-client-id-enforcement)
    - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting-sla)
    - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-oauth-token-introspection) (If Client ID enforcement is configured)
    - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-openid-token-enforcement) (If Client ID enforcement is configured)
    - [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-jwt-validation) (If Client ID enforcement is configured)
        
        Policies validating Client ID provide these authentication object properties:
        
        - `authentication.clientName`: Name of the contract’s client application
        - `authentication.clientId`: ID of the contract’s client application
        - `authentication.properties.slaId`: SLA ID assigned to the contract
- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-jwt-validation):
    
    - `authentication.properties.claims.<claimName>`: All claims provided by the JWT
- Multiple policies validate basic authentication credentials:
    
    - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-simple)
    - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-ldap)
        
        Policies validating basic authentication credentials provide these authentication object properties:
        
        - `authentication.principal`: Username passed as basic auth user

After your policy populates the authentication object, you can access the object in policies ordered after the authentication policy using DataWeave expressions. For example:

- Read a value from the authentication object:
    
    #\[authentication.properties.claims.exp\]
- Check if a JSON array or a JSON string JWT claim contains a specific value:
    
    #\[authentication.properties.claims.custom\_claim contains 'read'\]
- Remove sensitive headers, such as `Authorization`, for logging purposes:
    
    #\[attributes.headers -- "Authorization"\]

<!-- document id=e04e54850217d9fc61c7e2b51c112664d8a2fe29189f081dcf631e59c67b6992 url=/mulesoft/current/en-us/gateway/1.9/policies-flex-dataweave-support.md -->

---
product: Omni Gateway
version: 1.9
---

# DataWeave Support in Flex Gateway Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

[DataWeave](https://docs.mulesoft.com/dataweave/latest/) is the programming language designed by MuleSoft for data
transformation. It enables you to build a simple solution for a common integration developer use
case: read and parse data from one format, transform the data, and write it out as a different
format.

Flex Gateway supports a subset of DataWeave in policy configuration expressions. DataWeave is only
supported in included policies and custom policies created with PDK..

## Available Types

- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#null)

- `Boolean`

- `String`

- `Number` (Driven as 64 bits floating points)

- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#array-type)

- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#object-type) (Repeated keys are not
  available)

## Available Value Constructors for Types

- [`Boolean`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_boolean)

- [`String`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_string)

- [`Number`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_number)

- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_array)

## Unavailable Value Constructors for Types

- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_null) (Writing a `null` literal is not
  supported)

- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_object) (Objects can not be defined as
  literals)

## Available Flow Control Structures

- [`if else`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_if_else)

## Unavailable Flow Control Structures

- [`do`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_do)

## Available Selectors

- `Array[Number]`

- `Array[String]`

- `Object[String]`

- `String[Number]`

## Unavailable Selectors

- `Object[Number]`

## Available Equality and Relational Operators

- [`==`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)

- [`!=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)

- [`>=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)

- [`<=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)

## Available Logical Operators

- [`not`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)

- [`and`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)

- [`or`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)

## Available Default Operators

- [`default`](https://docs.mulesoft.com/dataweave/latest/dataweave-cookbook-defaults#example-of-using-the-keyword-default-to-set-a-default-value)

## Available Functions

### `++`

- [`++(Array<S>, Array<T>): Array<S | T>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus1)

- [`++(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus2)

### `contains`

- [`contains(Array<T>, Any): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains1)

- [`contains(String, String): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains2)

### `lower`

- [`lower(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower1)

- [`lower(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower2)

### `splitBy`

- [`splitBy(String, String): Array<String>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-splitby#splitby2)

### `sizeOf`

- [`sizeOf(Array<Any>): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof1)

- [`sizeOf(Object): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof2)

- [`sizeOf(String): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof4)

### `trim`

- [`trim(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim1)

- [`trim(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim2)

### `upper`

- [`upper(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper1)

- [`upper(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper2)

### `uuid`

- [`uuid(): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-uuid#uuid1)

### `dw::core::Strings::substringAfter`

- [`substringAfter(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter1)

- [`substringAfter(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter2)

### `dw::core::Strings::substringAfterLast`

- [`substringAfterLast(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast1)

- [`substringAfterLast(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast2)

### `dw::core::Strings::substringBefore`

- [`substringBefore(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore1)

- [`substringBefore(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore2)

### `dw::core::Strings::substringBeforeLast`

- [`substringBeforeLast(text: String, separator: String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast1)

- [`substringBeforeLast(text: Null, separator: String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast2)

## Available Predefined Variables

- [`attributes`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)

  - `attributes.headers`

  - `attributes.method` (Only available in request context)

  - `attributes.queryParams` (Only available in request context)

  - `attributes.queryString` (Only available in request context)

  - `attributes.requestPath` (Only available in request context)

  - `attributes.requestUri` (Only available in request context)

  - `attributes.localAddress` (Only available in request context)

  - `attributes.remoteAddress` (Only available in request context)

  - `attributes.scheme` (Only available in request context)

  - `attributes.version` (Only available in request context)

  - `attributes.statusCode` (Only available in response context)

- [`authentication`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)

  - `authentication.clientId`

  - `authentication.clientName`

  - `authentication.principal`

  - `authentication.properties`

- `payload`

  - Use the `payload` variable to read the request body as a string. You can’t parse this variable.

- [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)

  - Individual policies support different sets of variables. For information, refer to the policies
    listed in [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory).

<!-- document id=35f80b13f4fbfa7a47bb55787bf314b7e0841c4c63e8b38e36e78a0e803af737 url=/mulesoft/current/en-us/gateway/1.13/policies-dataweave-support.md -->

# DataWeave Support in Omni Gateway Policies

[DataWeave](https://docs.mulesoft.com/dataweave/latest/) is the programming language designed by MuleSoft for data transformation. It enables you to build a simple solution for a common integration developer use case: read and parse data from one format, transform the data, and write it out as a different format.

Omni Gateway supports a subset of DataWeave in policy configuration expressions. DataWeave is only supported in included policies and custom policies created with PDK..

## [](#available-types)Available Types

- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#null)
- `Boolean`
- `String`
- `Number` (Driven as 64 bits floating points)
- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#array-type)
- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#object-type) (Repeated keys are not available)

## [](#available-value-constructors-for-types)Available Value Constructors for Types

- [`Boolean`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_boolean)
- [`String`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_string)
- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_null)
- [`Number`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_number)
- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_array)

## [](#unavailable-value-constructors-for-types)Unavailable Value Constructors for Types

- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_object) (Objects can not be defined as literals)

## [](#available-flow-control-structures)Available Flow Control Structures

- [`if else`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_if_else)

## [](#unavailable-flow-control-structures)Unavailable Flow Control Structures

- [`do`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_do)

## [](#available-selectors)Available Selectors

- `Array[Number]`
- `Array[String]`
- `Object[String]`
- `String[Number]`

## [](#unavailable-selectors)Unavailable Selectors

- `Object[Number]`

## [](#available-equality-and-relational-operators)Available Equality and Relational Operators

- [`==`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`!=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`>=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`<=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)

## [](#available-logical-operators)Available Logical Operators

- [`not`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)
- [`and`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)
- [`or`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)

## [](#available-default-operators)Available Default Operators

- [`default`](https://docs.mulesoft.com/dataweave/latest/dataweave-cookbook-defaults#example-of-using-the-keyword-default-to-set-a-default-value)

## [](#available-functions)Available Functions

### [](#)`++`

- [`++(Array<S>, Array<T>): Array<S | T>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus1)
- [`++(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus2)

### [](#available-minus-operators)`--`

- [`--<S>(source: Array<S>, toRemove: Array<Any>): Array<S>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus1)
- [`--<K, V>(source: { (K)?: V }, toRemove: Object): { (K)?: V }`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus2)
- [`--(source: Object, keys: Array<String>)`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus3)

### [](#contains)`contains`

- [`contains(Array<T>, Any): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains1)
- [`contains(String, String): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains2)

### [](#lower)`lower`

- [`lower(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower1)
- [`lower(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower2)

### [](#splitby)`splitBy`

- [`splitBy(String, String): Array<String>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-splitby#splitby2)

### [](#sizeof)`sizeOf`

- [`sizeOf(Array<Any>): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof1)
- [`sizeOf(Object): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof2)
- [`sizeOf(String): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof4)

### [](#trim)`trim`

- [`trim(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim1)
- [`trim(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim2)

### [](#upper)`upper`

- [`upper(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper1)
- [`upper(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper2)

### [](#uuid)`uuid`

- [`uuid(): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-uuid#uuid1)

### [](#dwcorestringssubstringafter)`dw::core::Strings::substringAfter`

- [`substringAfter(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter1)
- [`substringAfter(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter2)

### [](#dwcorestringssubstringafterlast)`dw::core::Strings::substringAfterLast`

- [`substringAfterLast(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast1)
- [`substringAfterLast(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast2)

### [](#dwcorestringssubstringbefore)`dw::core::Strings::substringBefore`

- [`substringBefore(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore1)
- [`substringBefore(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore2)

### [](#dwcorestringssubstringbeforelast)`dw::core::Strings::substringBeforeLast`

- [`substringBeforeLast(text: String, separator: String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast1)
- [`substringBeforeLast(text: Null, separator: String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast2)

### [](#tobase64)toBase64

- [`toBase64(content: Binary): String`](https://docs.mulesoft.com/dataweave/latest/dw-binaries-functions-tobase64#tobase641)

### [](#frombase64)fromBase64

- [`fromBase64(base64String: String): Binary`](https://docs.mulesoft.com/dataweave/latest/dw-binaries-functions-frombase64#frombase641)

<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Omni Gateway doesn’t support DataWeave expressions with binary type results. To use the <code>dw::Binaries::fromBase64('dXNlcjpwYXNz')</code> function, transform the result to a string. Transform the binary output to a string with the <code>dw::util::Coercions::toString(binary: Binary, encoding: String): String</code> function. For example, <code><mark>[dw::util::Coercions::toString(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), 'UTF-8')]</mark></code>.
If using a different function that transforms the binary by default, such as <code>[splitBy(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), ':')]</code>, you can skip manually transforming the binary.</p>
</div>
</td>
</tr>
</tbody></table>

### [](#tobinary)toBinary

- [`toBinary(str: String, encoding: String): Binary`](https://docs.mulesoft.com/dataweave/latest/dw-coercions-functions-tobinary#tobinary1)

### [](#tostring)toString

- [`toString(binary: Binary, encoding: String): String`](https://docs.mulesoft.com/dataweave/latest/dw-coercions-functions-tostring#tostring3)

## [](#available-predefined-variables)Available Predefined Variables

- [`attributes`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - `attributes.headers`
    - `attributes.method` (Only available in request context)
    - `attributes.queryParams` (Only available in request context)
    - `attributes.queryString` (Only available in request context)
    - `attributes.requestPath` (Only available in request context)
    - `attributes.requestUri` (Only available in request context)
    - `attributes.localAddress` (Only available in request context)
    - `attributes.remoteAddress` (Only available in request context)
    - `attributes.scheme` (Only available in request context)
    - `attributes.version` (Only available in request context)
    - `attributes.statusCode` (Only available in response context)
- [`authentication`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - `authentication.clientId`
    - `authentication.clientName`
    - `authentication.principal`
    - `authentication.properties`
        
        To learn more about how to access the authentication object, see [Access the Authentication Object](#access-authentication-object).
- `payload`
    
    - Fields depend on the current payload. For example, `#[payload]` returns the body of the message.
- [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - Individual policies support different sets of variables. For information, refer to the policies listed in [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory).

## [](#dataweave-usage-examples)DataWeave Usage Examples

You can use DataWeave to extract different values from the request and response.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">The Omni Gateway Policy Development Kit (PDK) provides the <a href="https://github.com/mulesoft/pdk-custom-policy-examples/tree/main/dataweave">DataWeave example policy</a> that you can use to test DataWeave expressions.</td></tr></tbody></table>

For example, use DataWeave expressions to:

- Read a header:
    
    #\[attributes.headers.'my-header'\]
- Ensure a specific header is defined:
    
    #\[attributes.headers.'my-header' != null\]
- Check if a request has basic authorization:
    
    #\[lower(splitBy(attributes.headers.authorization default '', ' ')\[0\]) == 'basic'\]
- Check if a request contains `/some` path:
    
    #\[attributes.requestPath contains '/some'\]
- Check if a request doesn’t contain `/some` path:
    
    #\[not(attributes.requestPath contains '/some')\]
- Read the username from a `Basic` authorization header:
    
    #\[splitBy(dw::core::Binaries::fromBase64(dw::core::Strings::substringAfter(attributes.headers.authorization default '', 'Basic')), ':')\[0\]\]
- Read the password from a `Basic` authorization header:
    
    #\[splitBy(dw::core::Binaries::fromBase64(dw::core::Strings::substringAfter(attributes.headers.authorization default '', 'Basic ')), ':')\[1\]\]
- Read the first value of the `x-forwarded-for` header:
    
    #\[trim(splitBy(attributes.headers.'x-forwarded-for', ',')\[0\])\]
- Read the last value of the `x-forwarded-for` header:
    
    #\[trim(splitBy(attributes.headers.'x-forwarded-for', ',')\[-1\])\]
- Read the value from a `Cookie`:
    
    #\[trim(dw::core::Strings::substringBefore(dw::core::Strings::substringAfter(attributes.headers.Cookie default '', 'myCookieName='), ';'))\]
- Check if a single value or space-separated header contains a specific value:
    
    #\[splitBy(attributes.headers.scopes default '', ' ') contains 'read'\]

## [](#access-authentication-object)Access the Authentication Object

To access the [`authentication`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) object, you must first configure an authentication policy that populates the object.

The authentication policy you apply affects the available authentication object properties:

- Multiple policies can validate Client ID:
    
    - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-client-id-enforcement)
    - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting-sla)
    - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-oauth-token-introspection) (If Client ID enforcement is configured)
    - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-openid-token-enforcement) (If Client ID enforcement is configured)
    - [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-jwt-validation) (If Client ID enforcement is configured)
        
        Policies validating Client ID provide these authentication object properties:
        
        - `authentication.clientName`: Name of the contract’s client application
        - `authentication.clientId`: ID of the contract’s client application
        - `authentication.properties.slaId`: SLA ID assigned to the contract
- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-jwt-validation):
    
    - `authentication.properties.claims.<claimName>`: All claims provided by the JWT
- Multiple policies validate basic authentication credentials:
    
    - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-simple)
    - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-ldap)
        
        Policies validating basic authentication credentials provide these authentication object properties:
        
        - `authentication.principal`: Username passed as basic auth user

After your policy populates the authentication object, you can access the object in policies ordered after the authentication policy using DataWeave expressions. For example:

- Read a value from the authentication object:
    
    #\[authentication.properties.claims.exp\]
- Check if a JSON array or a JSON string JWT claim contains a specific value:
    
    #\[authentication.properties.claims.custom\_claim contains 'read'\]
- Remove sensitive headers, such as `Authorization`, for logging purposes:
    
    #\[attributes.headers -- "Authorization"\]

<!-- document id=23e0dfb62802df5fb85118714d6119ed2136538ebb175271a634973b7362dd9f url=/mulesoft/current/en-us/gateway/latest/policies-dataweave-support.md -->

# DataWeave Support in Omni Gateway Policies

[DataWeave](https://docs.mulesoft.com/dataweave/latest/) is the programming language designed by MuleSoft for data transformation. It enables you to build a simple solution for a common integration developer use case: read and parse data from one format, transform the data, and write it out as a different format.

Omni Gateway supports a subset of DataWeave in policy configuration expressions. DataWeave is only supported in included policies and custom policies created with PDK..

## [](#available-types)Available Types

- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#null)
- `Boolean`
- `String`
- `Number` (Driven as 64 bits floating points)
- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#array-type)
- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-type-system#object-type) (Repeated keys are not available)

## [](#available-value-constructors-for-types)Available Value Constructors for Types

- [`Boolean`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_boolean)
- [`String`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_string)
- [`Null`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_null)
- [`Number`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_number)
- [`Array`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_array)

## [](#unavailable-value-constructors-for-types)Unavailable Value Constructors for Types

- [`Object`](https://docs.mulesoft.com/dataweave/latest/dataweave-types#dw_type_object) (Objects can not be defined as literals)

## [](#available-flow-control-structures)Available Flow Control Structures

- [`if else`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_if_else)

## [](#unavailable-flow-control-structures)Unavailable Flow Control Structures

- [`do`](https://docs.mulesoft.com/dataweave/latest/dataweave-flow-control#control_flow_do)

## [](#available-selectors)Available Selectors

- `Array[Number]`
- `Array[String]`
- `Object[String]`
- `String[Number]`

## [](#unavailable-selectors)Unavailable Selectors

- `Object[Number]`

## [](#available-equality-and-relational-operators)Available Equality and Relational Operators

- [`==`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`!=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`>=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)
- [`<=`](https://docs.mulesoft.com/dataweave/latest/dw-operators#equality-and-relational-operators)

## [](#available-logical-operators)Available Logical Operators

- [`not`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)
- [`and`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)
- [`or`](https://docs.mulesoft.com/dataweave/latest/dw-operators#logical_operators)

## [](#available-default-operators)Available Default Operators

- [`default`](https://docs.mulesoft.com/dataweave/latest/dataweave-cookbook-defaults#example-of-using-the-keyword-default-to-set-a-default-value)

## [](#available-functions)Available Functions

### [](#)`++`

- [`++(Array<S>, Array<T>): Array<S | T>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus1)
- [`++(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-plusplus#plusplus2)

### [](#available-minus-operators)`--`

- [`--<S>(source: Array<S>, toRemove: Array<Any>): Array<S>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus1)
- [`--<K, V>(source: { (K)?: V }, toRemove: Object): { (K)?: V }`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus2)
- [`--(source: Object, keys: Array<String>)`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-minusminus#minusminus3)

### [](#contains)`contains`

- [`contains(Array<T>, Any): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains1)
- [`contains(String, String): Boolean`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-contains#contains2)

### [](#lower)`lower`

- [`lower(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower1)
- [`lower(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-lower#lower2)

### [](#splitby)`splitBy`

- [`splitBy(String, String): Array<String>`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-splitby#splitby2)

### [](#sizeof)`sizeOf`

- [`sizeOf(Array<Any>): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof1)
- [`sizeOf(Object): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof2)
- [`sizeOf(String): Number`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-sizeof#sizeof4)

### [](#trim)`trim`

- [`trim(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim1)
- [`trim(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-trim#trim2)

### [](#upper)`upper`

- [`upper(String): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper1)
- [`upper(Null): Null`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-upper#upper2)

### [](#uuid)`uuid`

- [`uuid(): String`](https://docs.mulesoft.com/dataweave/latest/dw-core-functions-uuid#uuid1)

### [](#dwcorestringssubstringafter)`dw::core::Strings::substringAfter`

- [`substringAfter(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter1)
- [`substringAfter(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafter#substringafter2)

### [](#dwcorestringssubstringafterlast)`dw::core::Strings::substringAfterLast`

- [`substringAfterLast(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast1)
- [`substringAfterLast(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringafterlast#substringafterlast2)

### [](#dwcorestringssubstringbefore)`dw::core::Strings::substringBefore`

- [`substringBefore(String, String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore1)
- [`substringBefore(Null, String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbefore#substringbefore2)

### [](#dwcorestringssubstringbeforelast)`dw::core::Strings::substringBeforeLast`

- [`substringBeforeLast(text: String, separator: String): String`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast1)
- [`substringBeforeLast(text: Null, separator: String): Null`](https://docs.mulesoft.com/dataweave/latest/dw-strings-functions-substringbeforelast#substringbeforelast2)

### [](#tobase64)toBase64

- [`toBase64(content: Binary): String`](https://docs.mulesoft.com/dataweave/latest/dw-binaries-functions-tobase64#tobase641)

### [](#frombase64)fromBase64

- [`fromBase64(base64String: String): Binary`](https://docs.mulesoft.com/dataweave/latest/dw-binaries-functions-frombase64#frombase641)

<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Omni Gateway doesn’t support DataWeave expressions with binary type results. To use the <code>dw::Binaries::fromBase64('dXNlcjpwYXNz')</code> function, transform the result to a string. Transform the binary output to a string with the <code>dw::util::Coercions::toString(binary: Binary, encoding: String): String</code> function. For example, <code><mark>[dw::util::Coercions::toString(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), 'UTF-8')]</mark></code>.
If using a different function that transforms the binary by default, such as <code>[splitBy(dw::core::Binaries::fromBase64('dXNlcjpwYXNz'), ':')]</code>, you can skip manually transforming the binary.</p>
</div>
</td>
</tr>
</tbody></table>

### [](#tobinary)toBinary

- [`toBinary(str: String, encoding: String): Binary`](https://docs.mulesoft.com/dataweave/latest/dw-coercions-functions-tobinary#tobinary1)

### [](#tostring)toString

- [`toString(binary: Binary, encoding: String): String`](https://docs.mulesoft.com/dataweave/latest/dw-coercions-functions-tostring#tostring3)

## [](#available-predefined-variables)Available Predefined Variables

- [`attributes`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - `attributes.headers`
    - `attributes.method` (Only available in request context)
    - `attributes.queryParams` (Only available in request context)
    - `attributes.queryString` (Only available in request context)
    - `attributes.requestPath` (Only available in request context)
    - `attributes.requestUri` (Only available in request context)
    - `attributes.localAddress` (Only available in request context)
    - `attributes.remoteAddress` (Only available in request context)
    - `attributes.scheme` (Only available in request context)
    - `attributes.version` (Only available in request context)
    - `attributes.statusCode` (Only available in response context)
- [`authentication`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - `authentication.clientId`
    - `authentication.clientName`
    - `authentication.principal`
    - `authentication.properties`
        
        To learn more about how to access the authentication object, see [Access the Authentication Object](#access-authentication-object).
- `payload`
    
    - Fields depend on the current payload. For example, `#[payload]` returns the body of the message.
- [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context)
    
    - Individual policies support different sets of variables. For information, refer to the policies listed in [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory).

## [](#dataweave-usage-examples)DataWeave Usage Examples

You can use DataWeave to extract different values from the request and response.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">The Omni Gateway Policy Development Kit (PDK) provides the <a href="https://github.com/mulesoft/pdk-custom-policy-examples/tree/main/dataweave">DataWeave example policy</a> that you can use to test DataWeave expressions.</td></tr></tbody></table>

For example, use DataWeave expressions to:

- Read a header:
    
    #\[attributes.headers.'my-header'\]
- Ensure a specific header is defined:
    
    #\[attributes.headers.'my-header' != null\]
- Check if a request has basic authorization:
    
    #\[lower(splitBy(attributes.headers.authorization default '', ' ')\[0\]) == 'basic'\]
- Check if a request contains `/some` path:
    
    #\[attributes.requestPath contains '/some'\]
- Check if a request doesn’t contain `/some` path:
    
    #\[not(attributes.requestPath contains '/some')\]
- Read the username from a `Basic` authorization header:
    
    #\[splitBy(dw::core::Binaries::fromBase64(dw::core::Strings::substringAfter(attributes.headers.authorization default '', 'Basic')), ':')\[0\]\]
- Read the password from a `Basic` authorization header:
    
    #\[splitBy(dw::core::Binaries::fromBase64(dw::core::Strings::substringAfter(attributes.headers.authorization default '', 'Basic ')), ':')\[1\]\]
- Read the first value of the `x-forwarded-for` header:
    
    #\[trim(splitBy(attributes.headers.'x-forwarded-for', ',')\[0\])\]
- Read the last value of the `x-forwarded-for` header:
    
    #\[trim(splitBy(attributes.headers.'x-forwarded-for', ',')\[-1\])\]
- Read the value from a `Cookie`:
    
    #\[trim(dw::core::Strings::substringBefore(dw::core::Strings::substringAfter(attributes.headers.Cookie default '', 'myCookieName='), ';'))\]
- Check if a single value or space-separated header contains a specific value:
    
    #\[splitBy(attributes.headers.scopes default '', ' ') contains 'read'\]

## [](#access-authentication-object)Access the Authentication Object

To access the [`authentication`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) object, you must first configure an authentication policy that populates the object.

The authentication policy you apply affects the available authentication object properties:

- Multiple policies can validate Client ID:
    
    - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-client-id-enforcement)
    - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting-sla)
    - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-oauth-token-introspection) (If Client ID enforcement is configured)
    - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-openid-token-enforcement) (If Client ID enforcement is configured)
    - [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation) (If Client ID enforcement is configured)
        
        Policies validating Client ID provide these authentication object properties:
        
        - `authentication.clientName`: Name of the contract’s client application
        - `authentication.clientId`: ID of the contract’s client application
        - `authentication.properties.slaId`: SLA ID assigned to the contract
- [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation):
    
    - `authentication.properties.claims.<claimName>`: All claims provided by the JWT
- Multiple policies validate basic authentication credentials:
    
    - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple)
    - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-ldap)
        
        Policies validating basic authentication credentials provide these authentication object properties:
        
        - `authentication.principal`: Username passed as basic auth user

After your policy populates the authentication object, you can access the object in policies ordered after the authentication policy using DataWeave expressions. For example:

- Read a value from the authentication object:
    
    #\[authentication.properties.claims.exp\]
- Check if a JSON array or a JSON string JWT claim contains a specific value:
    
    #\[authentication.properties.claims.custom\_claim contains 'read'\]
- Remove sensitive headers, such as `Authorization`, for logging purposes:
    
    #\[attributes.headers -- "Authorization"\]

<!-- document id=433a19c961e3b583cb61bce32118de34e8b87354eed9920dea598fc2741da142 url=/mulesoft/current/en-us/gateway/1.12/flex-local-configuration-reference-guide.md -->

---
product: Omni Gateway
version: 1.12
---

# Declarative Configuration Reference Guide

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway running in Local Mode supports two configuration models:

- The resource-based model, common in Kubernetes, is ideal for granular definitions. Resources each
  contain one of the following values for configuration `kind`:

  - `ApiInstance`

  - `Service`

  - `PolicyBinding`

  - `Configuration`

- The inline model is ideal for concise definitions, but is less versatile (for example, automated
  policies can only be applied in resource-based definitions.)

  Inline definitions contain a single `ApiInstance` value for configuration `kind`, under which
  services and policies are both defined.

![Diagram of the structure of API instances, services, and policy binding](/mulesoft/current/en-us/gateway/1.12/_images/gateway-configuration-models.png)

Refer to the [Examples](#examples) section for examples of both.

This reference guide describes the available resources that are applicable to either resource-based
configurations or inline configurations.

## API Instance

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: <api instance name>
namespace: # optional namespace name spec: address: <proxy address including port and path>
services: # optional map of upstream services <name>: address: <service address> routes: # optional
array of routes to service - config: # optional route configuration destinationPath:
<optional base path to upstream service> rules: # optional route rules policies: # optional array of
policies - policyRef: name: <name of the policy> namespace: <optional namespace of the policy>
config: # optional policy configuration rules: # optional policy rules

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance identifier that is used as a target reference for other resources, such as policy bindings.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The proxy address URL, including protocol, host, port and optional path. If the base path is specified, it must be absent in any <code>rules.path</code> attribute. Supported format: <code>protocol://host:port/path</code>, where <code>path</code> is optional, and <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of named services and their routes.</p></td></tr><tr><td><p><code>spec.services[name].address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address (and port). Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of routes configured for this API instance towards the service. If left empty, a default route will be established to the service that will route all traffic.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The configuration for this route. If left empty, a default configuration will be applied with an empty <code>destinationPath</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config.destinationPath</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The path to prepend to forwarded requests to the upstream service. For example, if "destinationPath: /api/v1", requests to this API instance with a path like "/orders" will be routed upstream to "/api/v1/orders".</p></td></tr><tr><td><p><code>spec.services[name].routes[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for this route. Refer to <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr><tr><td><p><code>spec.policies</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of policies to apply to this API Instance.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.policies[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy’s configuration. Refer to <a href="#policy-binding">spec.config</a> in Policy Binding. To use environment variables in <code>policies[#].config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.policies[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for applying this policy to the API Instance. <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr></tbody></table>

### API Instance Examples

The following resource specifies an `ApiInstance` with metadata that describes the instance
identifier. The `metadata.name` value is used as the target reference for other resources, such as
policy bindings. The `spec.services.routes.config.destinationPath` value prepends `/v1/apps` to the
specified paths under `rules`, acting in a similar manner as a base path.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name:
hello-flex-gateway-instance spec: address: http://0.0.0.0:8080 services: json: address:
https://<upstream address>:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) config: destinationPath: /v1/apps

#### Port Sharing

The following `ApiInstance` resources demonstrate API port sharing, with two distinct API instances
listening on port 8080.

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: httpbin-example
spec: address: http://0.0.0.0:8080/api/httpbin/ services: upstream: address: https://<upstream address>:443
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-example spec:
address: http://0.0.0.0:8080/api/json/ services: upstream: address: https://<upstream address>:443

Both services listen on port 8080, for example:

curl http://localhost:8080/api/httpbin/get -v curl http://localhost:8080/api/json/users/1 -v

> [!NOTE] The base path of APIs sharing a port must not clash. For example, the following path
> combination is not allowed:
>
> http://0.0.0.0:8080/cats http://0.0.0.0:8080/cats/dogs

> [!NOTE] TLS applies to the port. Therefore, the same TLS policy applies to all API instances
> sharing the port.

## Policy Binding

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: <policy binding name>
namespace: <namespace name> spec: targetRef: name: <name of api instance or upstream service>
namespace: <optional namespace of api instance or upstream service> policyRef: name: <policy name>
namespace: <optional policy namespace> config: # optional policy configuration order: # optional
policy read order rules: # optional policy rules

- path: <path regular expression> methods: <methods regular expression> host:
  <host regular expression> headers: <headers map> <header-name>: <header value regular expression>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The identifier of the policy binding.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.targetRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance or upstream service identifier to which the policy is bound.</p></td></tr><tr><td><p><code>spec.targetRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the target is defined.</p></td></tr><tr><td><p><code>spec.policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name. See the list of available policies.</p></td></tr><tr><td><p><code>spec.policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy configuration. The content of this field depends on the specified policy. See the list of available policies. To use environment variables in <code>config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.order</code></p></td><td><p>Optional</p></td><td><p>50</p></td><td><p>The policy read order in the overall policy execution chain.</p></td></tr><tr><td><p><code>spec.rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules that will determine if the policy applies to a given request. These rules are checked in an OR fashion. The first one to hold will enable applying the policy to the request. The attributes in each rule object apply in an AND fashion. If path and host are defined, both must match for that rule to hold true.</p></td></tr><tr><td><p><code>spec.rules[#].path</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request path.</p><p>Capture groups in this regular expression will be used to define path rewriting when routing the request upstream.</p><p>If "path: /api(/.*)", requests with the path /api/orders will be routed upstream as /orders.</p><p>Multiple capture groups can be specified, and the replacement will be the concatenation of all captured substrings.</p></td></tr><tr><td><p><code>spec.rules[#].host</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request host.</p></td></tr><tr><td><p><code>spec.rules[#].methods</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request method.</p></td></tr><tr><td><p><code>spec.rules[#].headers</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of header names and value regular expressions that must be present in the request.</p><p>Each entry’s key is the expected header name and the value is a regular expression to match the header value.</p></td></tr></tbody></table>

### Policy Binding Examples

The following resource binds a `route` policy to the API instance, routing traffic specified by the
`rules` to the proxy address specified in the `Service` configuration snippet:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-route namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
policyRef: name: route namespace: default config: destinationRef: name: json namespace: e-commerce
rules:

- path: /api/json(/.\*)

The following resource binds a `http-basic-authentication-flex` policy to the API instance -
requiring requests to include the basic credentials defined in `config.username` and
`config.password`. The policy is given a read order value of `2`.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-auth namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
namespace: e-commerce policyRef: name: http-basic-authentication-flex namespace: default config:
username: chris password: admin order: 2

### Environment Variables for Policy Bindings

Both policy binding resources and inline policy bindings support environment variables in `config`
fields. The environment variables available are dependent on your environment.

To reference your environment variable, specify your environment variable prefixed by `$`, for
example:

\- policyRef: name: http-basic-authentication-flex config: username:
$USERNAME
    password: $PASSWORD

## Service

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: <service name> namespace:
<namespace name> spec: address: <service address including port>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service identifier.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address URL, including protocol, host and port. Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr></tbody></table>

### Service Example

The following resource defines a `Service` with metadata that describes the service identifier. The
`metadata.namespace` value matches the namespace specified in the `ApiInstance` configuration. The
`spec.address` is the address of the API implementation:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json-example namespace:
e-commerce spec: address: https://<upstream address>:443/

## Configuration

Define a desired gateway state by creating a `Configuration` entity. `Configuration` entities
specify several runtime configuration aspects for Flex Gateway itself, such as [logging](#logging)
and [shared storage](#shared-storage). The definition includes the following:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: <value> namespace:
<namespace name> spec: logging: # logging configuration sharedStorage: # shared storage
configuration

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Configuration entity.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td><p>The namespace value used to isolate Configuration entities.</p></td></tr><tr><td><p><code>spec</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The configuration object that defines gateway characteristics. Objects include: <code>logging</code>, <code>sharedStorage</code>, <code>tls</code>.</p></td></tr></tbody></table>

### Logging

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Flex Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Flex Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

#### Logging Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: logging spec: logging:
outputs: - name: log-to-file type: file parameters: path: /var/log file: log.txt format: template
template: | \[{date}\]\[{logger}\]\[{level}\]\[{kind}\] {message} runtimeLogs: logLevel: info
outputs: - log-to-file accessLogs: outputs: - log-to-file

### Shared Storage

The `sharedStorage` object configures the gateway for shared storage. Production workflows should
use [Redis](https://redis.io/) (minimum version 4.0.0), though defining it is optional. If Redis is
not defined, shared storage services at port 4000 are still available but will use an in-memory
implementation.

Optionally, you can use Redis with Transport Layer Security (TLS) to protect sensitive data, prevent
unauthorized access, and maintain the reliability of your services.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: shared-storage-redis
spec: sharedStorage: redis: address: <string> // REQUIRED username: <string> // OPTIONAL password:
<string> // OPTIONAL db: <string> // OPTIONAL tls: // OPTIONAL trustedCA: <string> // OPTIONAL
certificate: // OPTIONAL keyPassphrase <string> // OPTIONAL key: <string> // REQUIRED crt: <string>
// REQUIRED alpn: <array> // OPTIONAL skipValidation: <boolean> // OPTIONAL minversion: <string> //
OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>sharedStorage.redis.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Redis instance address in <code>host:port</code> format</p></td></tr><tr><td><p><code>sharedStorage.redis.username</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user name</p></td></tr><tr><td><p><code>sharedStorage.redis.password</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user password</p></td></tr><tr><td><p><code>sharedStorage.redis.db</code></p></td><td><p>Optional</p></td><td><p>0</p></td><td><p>The Redis database number to use</p></td></tr><tr><td><p><code>sharedStorage.redis.tls</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis TLS configuration</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.trustedCA</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Root certificate authority to use when verifying server certificates</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Client certificate to present to the server</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.keyPassphrase</code></p></td><td><p>Optional</p></td><td><p><code>none</code></p></td><td><p>The certificate key passphrase. If specified, use the private key format that includes a DEK-Info header. If unspecified, the private key must not be encrypted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.key</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The private key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.crt</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The public key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.skipValidation</code></p></td><td><p>Optional</p></td><td><p><code>false</code></p></td><td><p>If true, any certificate presented by the server is accepted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.minversion</code></p></td><td><p>Optional</p></td><td><p><code>1.2</code></p></td><td><p>The minimum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.maxversion</code></p></td><td><p>Optional</p></td><td><p><code>1.3</code></p></td><td><p>The maximum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.alpn</code></p></td><td><p>Optional</p></td><td><p>Empty list</p></td><td><p>A prioritized list of supported application level protocols; for example, h2, http/1.1</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.ciphers</code></p></td><td><p>Optional</p></td><td></td><td></td></tr></tbody></table>

> [!NOTE] TLS/Redis supports the same ciphers as the [TLS policy](https://docs.mulesoft.com/gateway/1.12/policies-included-tls), except the
> following:
>
> - TLS\_RSA\_WITH\_NULL\_SHA
>
> - TLS\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_128\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_CHACHA20\_POLY1305\_SHA256

**Redis Shared Storage Example**

The Redis storage service is an implementation of a REST API object store that functions as a bridge
between the object store interface and a Redis backend.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

**Redis with TLS Shared Storage Example**

Optionally, you can use Redis with TLS to protect data and ensure secure communication.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

**Local Shared Storage Example**

The local storage service is an implementation of a REST API object store that saves data in memory.
All data is lost when Flex Gateway is stopped or restarted.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: rtm-config
  namespace: sales
spec:
  sharedStorage:
    local:
      enabled: true
```

## Examples

### Inline Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: api-example spec:
address: http://0.0.0.0:8080 services: api-example: address: https://<your url>:443/ routes: -
rules: - path: /api(/users/.\*) - path: /api(/comments/.\*) config: destinationPath: /v1/apps
policies: - policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Resource-Based Configuration Example

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec:
address: http://0.0.0.0:8080
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json spec: address: https://<your url>:443/
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-route
spec: targetRef: name: ingress-http policyRef: name: route config: destinationRef: name: json rules:

- path: /api(/users/.\*)
- path: /api(/comments/.\*)

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
ingress-http-authentication spec: targetRef: name: ingress-http policyRef: name:
http-basic-authentication-flex config: username: chris password: admin

<!-- document id=820a097525fde9d1d98719b7c0a21b3491faaa2f69a2fb7e0d8d7d437e52c400 url=/mulesoft/current/en-us/gateway/1.13/local-configuration-reference-guide.md -->

---
product: Omni Gateway
version: 1.13
---

# Declarative Configuration Reference Guide

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Local Mode supports two configuration models:

- The resource-based model, common in Kubernetes, is ideal for granular definitions. Resources each
  contain one of the following values for configuration `kind`:

  - `ApiInstance`

  - `Service`

  - `PolicyBinding`

  - `Configuration`

- The inline model is ideal for concise definitions, but is less versatile (for example, automated
  policies can only be applied in resource-based definitions.)

  Inline definitions contain a single `ApiInstance` value for configuration `kind`, under which
  services and policies are both defined.

![Diagram of the structure of API instances, services, and policy binding](/mulesoft/current/en-us/gateway/1.13/_images/gateway-configuration-models.png)

Refer to the [Examples](#examples) section for examples of both.

This reference guide describes the available resources that are applicable to either resource-based
configurations or inline configurations.

## API Instance

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: <api instance name>
namespace: # optional namespace name spec: address: <proxy address including port and path>
services: # optional map of upstream services <name>: address: <service address> routes: # optional
array of routes to service - config: # optional route configuration destinationPath:
<optional base path to upstream service> rules: # optional route rules policies: # optional array of
policies - policyRef: name: <name of the policy> namespace: <optional namespace of the policy>
config: # optional policy configuration rules: # optional policy rules

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance identifier that is used as a target reference for other resources, such as policy bindings.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The proxy address URL, including protocol, host, port and optional path. If the base path is specified, it must be absent in any <code>rules.path</code> attribute. Supported format: <code>protocol://host:port/path</code>, where <code>path</code> is optional, and <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of named services and their routes.</p></td></tr><tr><td><p><code>spec.services[name].address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address (and port). Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of routes configured for this API instance towards the service. If left empty, a default route will be established to the service that will route all traffic.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The configuration for this route. If left empty, a default configuration will be applied with an empty <code>destinationPath</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config.destinationPath</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The path to prepend to forwarded requests to the upstream service. For example, if "destinationPath: /api/v1", requests to this API instance with a path like "/orders" will be routed upstream to "/api/v1/orders".</p></td></tr><tr><td><p><code>spec.services[name].routes[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for this route. Refer to <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr><tr><td><p><code>spec.policies</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of policies to apply to this API Instance.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.policies[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy’s configuration. Refer to <a href="#policy-binding">spec.config</a> in Policy Binding. To use environment variables in <code>policies[#].config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.policies[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for applying this policy to the API Instance. <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr></tbody></table>

### API Instance Examples

The following resource specifies an `ApiInstance` with metadata that describes the instance
identifier. The `metadata.name` value is used as the target reference for other resources, such as
policy bindings. The `spec.services.routes.config.destinationPath` value prepends `/v1/apps` to the
specified paths under `rules`, acting in a similar manner as a base path.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name:
hello-flex-gateway-instance spec: address: http://0.0.0.0:8080 services: json: address:
https://<upstream address>:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) config: destinationPath: /v1/apps

#### Port Sharing

The following `ApiInstance` resources demonstrate API port sharing, with two distinct API instances
listening on port 8080.

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: httpbin-example
spec: address: http://0.0.0.0:8080/api/httpbin/ services: upstream: address: https://<upstream address>:443
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-example spec:
address: http://0.0.0.0:8080/api/json/ services: upstream: address: https://<upstream address>:443

Both services listen on port 8080, for example:

curl http://localhost:8080/api/httpbin/get -v curl http://localhost:8080/api/json/users/1 -v

> [!NOTE] The base path of APIs sharing a port must not clash. For example, the following path
> combination is not allowed:
>
> http://0.0.0.0:8080/cats http://0.0.0.0:8080/cats/dogs

> [!NOTE] TLS applies to the port. Therefore, the same TLS policy applies to all API instances
> sharing the port.

## Policy Binding

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: <policy binding name>
namespace: <namespace name> spec: targetRef: name: <name of api instance or upstream service>
namespace: <optional namespace of api instance or upstream service> policyRef: name: <policy name>
namespace: <optional policy namespace> config: # optional policy configuration order: # optional
policy read order rules: # optional policy rules

- path: <path regular expression> methods: <methods regular expression> host:
  <host regular expression> headers: <headers map> <header-name>: <header value regular expression>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The identifier of the policy binding.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.targetRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance or upstream service identifier to which the policy is bound.</p></td></tr><tr><td><p><code>spec.targetRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the target is defined.</p></td></tr><tr><td><p><code>spec.policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name. See the list of available policies.</p></td></tr><tr><td><p><code>spec.policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy configuration. The content of this field depends on the specified policy. See the list of available policies. To use environment variables in <code>config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.order</code></p></td><td><p>Optional</p></td><td><p>50</p></td><td><p>The policy read order in the overall policy execution chain.</p></td></tr><tr><td><p><code>spec.rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules that will determine if the policy applies to a given request. These rules are checked in an OR fashion. The first one to hold will enable applying the policy to the request. The attributes in each rule object apply in an AND fashion. If path and host are defined, both must match for that rule to hold true.</p></td></tr><tr><td><p><code>spec.rules[#].path</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request path.</p><p>Capture groups in this regular expression will be used to define path rewriting when routing the request upstream.</p><p>If "path: /api(/.*)", requests with the path /api/orders will be routed upstream as /orders.</p><p>Multiple capture groups can be specified, and the replacement will be the concatenation of all captured substrings.</p></td></tr><tr><td><p><code>spec.rules[#].host</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request host.</p></td></tr><tr><td><p><code>spec.rules[#].methods</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request method.</p></td></tr><tr><td><p><code>spec.rules[#].headers</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of header names and value regular expressions that must be present in the request.</p><p>Each entry’s key is the expected header name and the value is a regular expression to match the header value.</p></td></tr></tbody></table>

### Policy Binding Examples

The following resource binds a `route` policy to the API instance, routing traffic specified by the
`rules` to the proxy address specified in the `Service` configuration snippet:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-route namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
policyRef: name: route namespace: default config: destinationRef: name: json namespace: e-commerce
rules:

- path: /api/json(/.\*)

The following resource binds a `http-basic-authentication-flex` policy to the API instance -
requiring requests to include the basic credentials defined in `config.username` and
`config.password`. The policy is given a read order value of `2`.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-auth namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
namespace: e-commerce policyRef: name: http-basic-authentication-flex namespace: default config:
username: chris password: admin order: 2

### Environment Variables for Policy Bindings

Both policy binding resources and inline policy bindings support environment variables in `config`
fields. The environment variables available are dependent on your environment.

To reference your environment variable, specify your environment variable prefixed by `$`, for
example:

\- policyRef: name: http-basic-authentication-flex config: username:
$USERNAME
    password: $PASSWORD

## Service

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: <service name> namespace:
<namespace name> spec: address: <service address including port>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service identifier.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address URL, including protocol, host and port. Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr></tbody></table>

### Service Example

The following resource defines a `Service` with metadata that describes the service identifier. The
`metadata.namespace` value matches the namespace specified in the `ApiInstance` configuration. The
`spec.address` is the address of the API implementation:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json-example namespace:
e-commerce spec: address: https://<upstream address>:443/

## Configuration

Define a desired gateway state by creating a `Configuration` entity. `Configuration` entities
specify several runtime configuration aspects for Omni Gateway itself, such as [logging](#logging)
and [shared storage](#shared-storage). The definition includes the following:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: <value> namespace:
<namespace name> spec: logging: # logging configuration sharedStorage: # shared storage
configuration

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Configuration entity.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td><p>The namespace value used to isolate Configuration entities.</p></td></tr><tr><td><p><code>spec</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The configuration object that defines gateway characteristics. Objects include: <code>logging</code>, <code>sharedStorage</code>, <code>tls</code>.</p></td></tr></tbody></table>

### Logging

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Omni Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Omni Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

#### Logging Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: logging spec: logging:
outputs: - name: log-to-file type: file parameters: path: /var/log file: log.txt format: template
template: | \[{date}\]\[{logger}\]\[{level}\]\[{kind}\] {message} runtimeLogs: logLevel: info
outputs: - log-to-file accessLogs: outputs: - log-to-file

### Shared Storage

The `sharedStorage` object configures the gateway for shared storage. Omni Gateway supports three
types of shared storage:

- **Distributed shared storage**: Enables multiple gateway replicas to share state across a
  distributed deployment. Data is lost when all replicas go down (scaled to zero replicas).

- **Redis shared storage**: Provides persistent storage when all replicas go down (scaled to zero
  replicas). Requires [Redis](https://redis.io/) (minimum version 4.0.0).

- **Local shared storage**: In-memory implementation. All data is lost when Omni Gateway is stopped
  or restarted.

Optionally, you can use Redis with Transport Layer Security (TLS) to protect sensitive data, prevent
unauthorized access, and maintain the reliability of your services.

#### Distributed Shared Storage

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: api-shared-storage
spec: sharedStorage: objectStore: url: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>sharedStorage.objectStore.url</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The distributed shared storage URL in the format <code>distributed://&lt;bind-address&gt;:&lt;port&gt;?join=&lt;host1&gt;:&lt;port1&gt;,&lt;host2&gt;:&lt;port2&gt;,…​</code></p></td></tr></tbody></table>

#### Redis Shared Storage

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: shared-storage-redis
spec: sharedStorage: redis: address: <string> // REQUIRED username: <string> // OPTIONAL password:
<string> // OPTIONAL db: <string> // OPTIONAL tls: // OPTIONAL trustedCA: <string> // OPTIONAL
certificate: // OPTIONAL keyPassphrase <string> // OPTIONAL key: <string> // REQUIRED crt: <string>
// REQUIRED alpn: <array> // OPTIONAL skipValidation: <boolean> // OPTIONAL minversion: <string> //
OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>sharedStorage.redis.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Redis instance address in <code>host:port</code> format</p></td></tr><tr><td><p><code>sharedStorage.redis.username</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user name</p></td></tr><tr><td><p><code>sharedStorage.redis.password</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user password</p></td></tr><tr><td><p><code>sharedStorage.redis.db</code></p></td><td><p>Optional</p></td><td><p>0</p></td><td><p>The Redis database number to use</p></td></tr><tr><td><p><code>sharedStorage.redis.tls</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis TLS configuration</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.trustedCA</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Root certificate authority to use when verifying server certificates</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Client certificate to present to the server</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.keyPassphrase</code></p></td><td><p>Optional</p></td><td><p><code>none</code></p></td><td><p>The certificate key passphrase. If specified, use the private key format that includes a DEK-Info header. If unspecified, the private key must not be encrypted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.key</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The private key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.crt</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The public key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.skipValidation</code></p></td><td><p>Optional</p></td><td><p><code>false</code></p></td><td><p>If true, any certificate presented by the server is accepted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.minversion</code></p></td><td><p>Optional</p></td><td><p><code>1.2</code></p></td><td><p>The minimum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.maxversion</code></p></td><td><p>Optional</p></td><td><p><code>1.3</code></p></td><td><p>The maximum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.alpn</code></p></td><td><p>Optional</p></td><td><p>Empty list</p></td><td><p>A prioritized list of supported application level protocols; for example, h2, http/1.1</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.ciphers</code></p></td><td><p>Optional</p></td><td></td><td></td></tr></tbody></table>

> [!NOTE] TLS/Redis supports the same ciphers as the [TLS policy](https://docs.mulesoft.com/gateway/1.13/policies-included-tls), except the
> following:
>
> - TLS\_RSA\_WITH\_NULL\_SHA
>
> - TLS\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_128\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_CHACHA20\_POLY1305\_SHA256

**Redis Shared Storage Example**

The Redis storage service is an implementation of a REST API object store that functions as a bridge
between the object store interface and a Redis backend.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

**Redis with TLS Shared Storage Example**

Optionally, you can use Redis with TLS to protect data and ensure secure communication.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

**Distributed Shared Storage Example**

Distributed shared storage enables multiple gateway replicas to share state across a distributed
deployment. Data is not persistent and is lost after gateway restarts.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: api-shared-storage
spec:
  sharedStorage:
    objectStore:
      url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

**Local Shared Storage Example**

The local storage service is an implementation of a REST API object store that saves data in memory.
All data is lost when Omni Gateway is stopped or restarted.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: rtm-config
  namespace: sales
spec:
  sharedStorage:
    local:
      enabled: true
```

## Examples

### Inline Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: api-example spec:
address: http://0.0.0.0:8080 services: api-example: address: https://<your url>:443/ routes: -
rules: - path: /api(/users/.\*) - path: /api(/comments/.\*) config: destinationPath: /v1/apps
policies: - policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Resource-Based Configuration Example

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec:
address: http://0.0.0.0:8080
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json spec: address: https://<your url>:443/
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-route
spec: targetRef: name: ingress-http policyRef: name: route config: destinationRef: name: json rules:

- path: /api(/users/.\*)
- path: /api(/comments/.\*)

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
ingress-http-authentication spec: targetRef: name: ingress-http policyRef: name:
http-basic-authentication-flex config: username: chris password: admin

<!-- document id=9706e2c31abd57590d5c03e7193e24e034b50c19640fa40c277d12eeb7d52d58 url=/mulesoft/current/en-us/gateway/1.9/flex-local-configuration-reference-guide.md -->

---
product: Omni Gateway
version: 1.9
---

# Declarative Configuration Reference Guide

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway running in Local Mode supports two configuration models:

- The resource-based model, common in Kubernetes, is ideal for granular definitions. Resources each
  contain one of the following values for configuration `kind`:

  - `ApiInstance`

  - `Service`

  - `PolicyBinding`

  - `Configuration`

- The inline model is ideal for concise definitions, but is less versatile (for example, automated
  policies can only be applied in resource-based definitions.)

  Inline definitions contain a single `ApiInstance` value for configuration `kind`, under which
  services and policies are both defined.

![Diagram of the structure of API instances, services, and policy binding](/mulesoft/current/en-us/gateway/1.9/_images/gateway-configuration-models.png)

Refer to the [Examples](#examples) section for examples of both.

This reference guide describes the available resources that are applicable to either resource-based
configurations or inline configurations.

## API Instance

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: <api instance name>
namespace: # optional namespace name spec: address: <proxy address including port and path>
services: # optional map of upstream services <name>: address: <service address> routes: # optional
array of routes to service - config: # optional route configuration destinationPath:
<optional base path to upstream service> rules: # optional route rules policies: # optional array of
policies - policyRef: name: <name of the policy> namespace: <optional namespace of the policy>
config: # optional policy configuration rules: # optional policy rules

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance identifier that is used as a target reference for other resources, such as policy bindings.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The proxy address URL, including protocol, host, port and optional path. If the base path is specified, it must be absent in any <code>rules.path</code> attribute. Supported format: <code>protocol://host:port/path</code>, where <code>path</code> is optional, and <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of named services and their routes.</p></td></tr><tr><td><p><code>spec.services[name].address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address (and port). Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of routes configured for this API instance towards the service. If left empty, a default route will be established to the service that will route all traffic.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The configuration for this route. If left empty, a default configuration will be applied with an empty <code>destinationPath</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config.destinationPath</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The path to prepend to forwarded requests to the upstream service. For example, if "destinationPath: /api/v1", requests to this API instance with a path like "/orders" will be routed upstream to "/api/v1/orders".</p></td></tr><tr><td><p><code>spec.services[name].routes[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for this route. Refer to <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr><tr><td><p><code>spec.policies</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of policies to apply to this API Instance.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.policies[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy’s configuration. Refer to <a href="#policy-binding">spec.config</a> in Policy Binding. To use environment variables in <code>policies[#].config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.policies[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for applying this policy to the API Instance. <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr></tbody></table>

### API Instance Examples

The following resource specifies an `ApiInstance` with metadata that describes the instance
identifier. The `metadata.name` value is used as the target reference for other resources, such as
policy bindings. The `spec.services.routes.config.destinationPath` value prepends `/v1/apps` to the
specified paths under `rules`, acting in a similar manner as a base path.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name:
hello-flex-gateway-instance spec: address: http://0.0.0.0:8080 services: json: address:
https://<upstream address>:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) config: destinationPath: /v1/apps

#### Port Sharing

The following `ApiInstance` resources demonstrate API port sharing, with two distinct API instances
listening on port 8080.

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: httpbin-example
spec: address: http://0.0.0.0:8080/api/httpbin/ services: upstream: address: https://<upstream address>:443
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-example spec:
address: http://0.0.0.0:8080/api/json/ services: upstream: address: https://<upstream address>:443

Both services listen on port 8080, for example:

curl http://localhost:8080/api/httpbin/get -v curl http://localhost:8080/api/json/users/1 -v

> [!NOTE] The base path of APIs sharing a port must not clash. For example, the following path
> combination is not allowed:
>
> http://0.0.0.0:8080/cats http://0.0.0.0:8080/cats/dogs

> [!NOTE] TLS applies to the port. Therefore, the same TLS policy applies to all API instances
> sharing the port.

## Policy Binding

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: <policy binding name>
namespace: <namespace name> spec: targetRef: name: <name of api instance or upstream service>
namespace: <optional namespace of api instance or upstream service> policyRef: name: <policy name>
namespace: <optional policy namespace> config: # optional policy configuration order: # optional
policy read order rules: # optional policy rules

- path: <path regular expression> methods: <methods regular expression> host:
  <host regular expression> headers: <headers map> <header-name>: <header value regular expression>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The identifier of the policy binding.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.targetRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance or upstream service identifier to which the policy is bound.</p></td></tr><tr><td><p><code>spec.targetRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the target is defined.</p></td></tr><tr><td><p><code>spec.policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name. See the list of available policies.</p></td></tr><tr><td><p><code>spec.policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy configuration. The content of this field depends on the specified policy. See the list of available policies. To use environment variables in <code>config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.order</code></p></td><td><p>Optional</p></td><td><p>50</p></td><td><p>The policy read order in the overall policy execution chain.</p></td></tr><tr><td><p><code>spec.rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules that will determine if the policy applies to a given request. These rules are checked in an OR fashion. The first one to hold will enable applying the policy to the request. The attributes in each rule object apply in an AND fashion. If path and host are defined, both must match for that rule to hold true.</p></td></tr><tr><td><p><code>spec.rules[#].path</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request path.</p><p>Capture groups in this regular expression will be used to define path rewriting when routing the request upstream.</p><p>If "path: /api(/.*)", requests with the path /api/orders will be routed upstream as /orders.</p><p>Multiple capture groups can be specified, and the replacement will be the concatenation of all captured substrings.</p></td></tr><tr><td><p><code>spec.rules[#].host</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request host.</p></td></tr><tr><td><p><code>spec.rules[#].methods</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request method.</p></td></tr><tr><td><p><code>spec.rules[#].headers</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of header names and value regular expressions that must be present in the request.</p><p>Each entry’s key is the expected header name and the value is a regular expression to match the header value.</p></td></tr></tbody></table>

### Policy Binding Examples

The following resource binds a `route` policy to the API instance, routing traffic specified by the
`rules` to the proxy address specified in the `Service` configuration snippet:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-route namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
policyRef: name: route namespace: default config: destinationRef: name: json namespace: e-commerce
rules:

- path: /api/json(/.\*)

The following resource binds a `http-basic-authentication-flex` policy to the API instance -
requiring requests to include the basic credentials defined in `config.username` and
`config.password`. The policy is given a read order value of `2`.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-auth namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
namespace: e-commerce policyRef: name: http-basic-authentication-flex namespace: default config:
username: chris password: admin order: 2

### Environment Variables for Policy Bindings

Both policy binding resources and inline policy bindings support environment variables in `config`
fields. The environment variables available are dependent on your environment.

To reference your environment variable, specify your environment variable prefixed by `$`, for
example:

\- policyRef: name: http-basic-authentication-flex config: username:
$USERNAME
    password: $PASSWORD

## Service

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: <service name> namespace:
<namespace name> spec: address: <service address including port>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service identifier.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address URL, including protocol, host and port. Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr></tbody></table>

### Service Example

The following resource defines a `Service` with metadata that describes the service identifier. The
`metadata.namespace` value matches the namespace specified in the `ApiInstance` configuration. The
`spec.address` is the address of the API implementation:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json-example namespace:
e-commerce spec: address: https://<upstream address>:443/

## Configuration

Define a desired gateway state by creating a `Configuration` entity. `Configuration` entities
specify several runtime configuration aspects for Flex Gateway itself, such as [logging](#logging)
and [shared storage](#shared-storage). The definition includes the following:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: <value> namespace:
<namespace name> spec: logging: # logging configuration sharedStorage: # shared storage
configuration

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Configuration entity.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td><p>The namespace value used to isolate Configuration entities.</p></td></tr><tr><td><p><code>spec</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The configuration object that defines gateway characteristics. Objects include: <code>logging</code>, <code>sharedStorage</code>, <code>tls</code>.</p></td></tr></tbody></table>

### Logging

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.0 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Flex Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Flex Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

#### Logging Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: logging spec: logging:
outputs: - name: log-to-file type: file parameters: path: /var/log file: log.txt format: template
template: | \[{date}\]\[{logger}\]\[{level}\]\[{kind}\] {message} runtimeLogs: logLevel: info
outputs: - log-to-file accessLogs: outputs: - log-to-file

### Shared Storage

The `sharedStorage` object configures the gateway for shared storage. Production workflows should
use [Redis](https://redis.io/) (minimum version 4.0.0), though defining it is optional. If Redis is
not defined, shared storage services at port 4000 are still available but will use an in-memory
implementation.

Optionally, you can use Redis with Transport Layer Security (TLS) to protect sensitive data, prevent
unauthorized access, and maintain the reliability of your services.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: shared-storage-redis
spec: sharedStorage: redis: address: <string> // REQUIRED username: <string> // OPTIONAL password:
<string> // OPTIONAL db: <string> // OPTIONAL tls: // OPTIONAL trustedCA: <string> // OPTIONAL
certificate: // OPTIONAL keyPassphrase <string> // OPTIONAL key: <string> // REQUIRED crt: <string>
// REQUIRED alpn: <array> // OPTIONAL skipValidation: <boolean> // OPTIONAL minversion: <string> //
OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>sharedStorage.redis.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Redis instance address in <code>host:port</code> format</p></td></tr><tr><td><p><code>sharedStorage.redis.username</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user name</p></td></tr><tr><td><p><code>sharedStorage.redis.password</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user password</p></td></tr><tr><td><p><code>sharedStorage.redis.db</code></p></td><td><p>Optional</p></td><td><p>0</p></td><td><p>The Redis database number to use</p></td></tr><tr><td><p><code>sharedStorage.redis.tls</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis TLS configuration</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.trustedCA</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Root certificate authority to use when verifying server certificates</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Client certificate to present to the server</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.keyPassphrase</code></p></td><td><p>Optional</p></td><td><p><code>none</code></p></td><td><p>The certificate key passphrase. If specified, use the private key format that includes a DEK-Info header. If unspecified, the private key must not be encrypted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.key</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The private key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.crt</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The public key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.skipValidation</code></p></td><td><p>Optional</p></td><td><p><code>false</code></p></td><td><p>If true, any certificate presented by the server is accepted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.minversion</code></p></td><td><p>Optional</p></td><td><p><code>1.2</code></p></td><td><p>The minimum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.maxversion</code></p></td><td><p>Optional</p></td><td><p><code>1.3</code></p></td><td><p>The maximum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.alpn</code></p></td><td><p>Optional</p></td><td><p>Empty list</p></td><td><p>A prioritized list of supported application level protocols; for example, h2, http/1.1</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.ciphers</code></p></td><td><p>Optional</p></td><td></td><td></td></tr></tbody></table>

> [!NOTE] TLS/Redis supports the same ciphers as the [TLS policy](https://docs.mulesoft.com/gateway/1.9/policies-included-tls), except the
> following:
>
> - TLS\_RSA\_WITH\_NULL\_SHA
>
> - TLS\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_128\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_CHACHA20\_POLY1305\_SHA256

**Redis Shared Storage Example**

The Redis storage service is an implementation of a REST API object store that functions as a bridge
between the object store interface and a Redis backend.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

**Redis with TLS Shared Storage Example**

Optionally, you can use Redis with TLS to protect data and ensure secure communication.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

**Local Shared Storage Example**

The local storage service is an implementation of a REST API object store that saves data in memory.
All data is lost when Flex Gateway is stopped or restarted.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: rtm-config
  namespace: sales
spec:
  sharedStorage:
    local:
      enabled: true
```

## Examples

### Inline Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: api-example spec:
address: http://0.0.0.0:8080 services: api-example: address: https://<your url>:443/ routes: -
rules: - path: /api(/users/.\*) - path: /api(/comments/.\*) config: destinationPath: /v1/apps
policies: - policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Resource-Based Configuration Example

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec:
address: http://0.0.0.0:8080
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json spec: address: https://<your url>:443/
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-route
spec: targetRef: name: ingress-http policyRef: name: route config: destinationRef: name: json rules:

- path: /api(/users/.\*)
- path: /api(/comments/.\*)

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
ingress-http-authentication spec: targetRef: name: ingress-http policyRef: name:
http-basic-authentication-flex config: username: chris password: admin

<!-- document id=ff310e8f700387c9f7001596d64a9b54b82831305f3e229991099ce103d4964f url=/mulesoft/current/en-us/gateway/latest/local-configuration-reference-guide.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Declarative Configuration Reference Guide

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Local Mode supports two configuration models:

- The resource-based model, common in Kubernetes, is ideal for granular definitions. Resources each
  contain one of the following values for configuration `kind`:

  - `ApiInstance`

  - `Service`

  - `PolicyBinding`

  - `Configuration`

- The inline model is ideal for concise definitions, but is less versatile (for example, automated
  policies can only be applied in resource-based definitions.)

  Inline definitions contain a single `ApiInstance` value for configuration `kind`, under which
  services and policies are both defined.

![Diagram of the structure of API instances, services, and policy binding](/mulesoft/current/en-us/gateway/latest/_images/gateway-configuration-models.png)

Refer to the [Examples](#examples) section for examples of both.

This reference guide describes the available resources that are applicable to either resource-based
configurations or inline configurations.

## API Instance

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: <api instance name>
namespace: # optional namespace name spec: address: <proxy address including port and path>
services: # optional map of upstream services <name>: address: <service address> routes: # optional
array of routes to service - config: # optional route configuration destinationPath:
<optional base path to upstream service> rules: # optional route rules policies: # optional array of
policies - policyRef: name: <name of the policy> namespace: <optional namespace of the policy>
config: # optional policy configuration rules: # optional policy rules

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance identifier that is used as a target reference for other resources, such as policy bindings.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The proxy address URL, including protocol, host, port and optional path. If the base path is specified, it must be absent in any <code>rules.path</code> attribute. Supported format: <code>protocol://host:port/path</code>, where <code>path</code> is optional, and <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of named services and their routes.</p></td></tr><tr><td><p><code>spec.services[name].address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address (and port). Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of routes configured for this API instance towards the service. If left empty, a default route will be established to the service that will route all traffic.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The configuration for this route. If left empty, a default configuration will be applied with an empty <code>destinationPath</code>.</p></td></tr><tr><td><p><code>spec.services[name].routes[#].config.destinationPath</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The path to prepend to forwarded requests to the upstream service. For example, if "destinationPath: /api/v1", requests to this API instance with a path like "/orders" will be routed upstream to "/api/v1/orders".</p></td></tr><tr><td><p><code>spec.services[name].routes[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for this route. Refer to <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr><tr><td><p><code>spec.policies</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of policies to apply to this API Instance.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name.</p></td></tr><tr><td><p><code>spec.policies[#].policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.policies[#].config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy’s configuration. Refer to <a href="#policy-binding">spec.config</a> in Policy Binding. To use environment variables in <code>policies[#].config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.policies[#].rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules for applying this policy to the API Instance. <a href="#policy-binding">spec.rules</a> in Policy Binding.</p></td></tr></tbody></table>

### API Instance Examples

The following resource specifies an `ApiInstance` with metadata that describes the instance
identifier. The `metadata.name` value is used as the target reference for other resources, such as
policy bindings. The `spec.services.routes.config.destinationPath` value prepends `/v1/apps` to the
specified paths under `rules`, acting in a similar manner as a base path.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name:
hello-flex-gateway-instance spec: address: http://0.0.0.0:8080 services: json: address:
https://<upstream address>:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) config: destinationPath: /v1/apps

#### Port Sharing

The following `ApiInstance` resources demonstrate API port sharing, with two distinct API instances
listening on port 8080.

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: httpbin-example
spec: address: http://0.0.0.0:8080/api/httpbin/ services: upstream: address: https://<upstream address>:443
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-example spec:
address: http://0.0.0.0:8080/api/json/ services: upstream: address: https://<upstream address>:443

Both services listen on port 8080, for example:

curl http://localhost:8080/api/httpbin/get -v curl http://localhost:8080/api/json/users/1 -v

> [!NOTE] The base path of APIs sharing a port must not clash. For example, the following path
> combination is not allowed:
>
> http://0.0.0.0:8080/cats http://0.0.0.0:8080/cats/dogs

> [!NOTE] TLS applies to the port. Therefore, the same TLS policy applies to all API instances
> sharing the port.

## Policy Binding

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: <policy binding name>
namespace: <namespace name> spec: targetRef: name: <name of api instance or upstream service>
namespace: <optional namespace of api instance or upstream service> policyRef: name: <policy name>
namespace: <optional policy namespace> config: # optional policy configuration order: # optional
policy read order rules: # optional policy rules

- path: <path regular expression> methods: <methods regular expression> host:
  <host regular expression> headers: <headers map> <header-name>: <header value regular expression>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The identifier of the policy binding.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.targetRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The API instance or upstream service identifier to which the policy is bound.</p></td></tr><tr><td><p><code>spec.targetRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the target is defined.</p></td></tr><tr><td><p><code>spec.policyRef.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The policy name. See the list of available policies.</p></td></tr><tr><td><p><code>spec.policyRef.namespace</code></p></td><td><p>Optional</p></td><td><p>The value of <code>metadata.namespace</code></p></td><td><p>The namespace where the policy is defined. For provided policies, the value of this field should be <code>default</code>.</p></td></tr><tr><td><p><code>spec.config</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The policy configuration. The content of this field depends on the specified policy. See the list of available policies. To use environment variables in <code>config</code> fields, refer to <a href="#environment-variables">Environment Variables for Policy Bindings</a>.</p></td></tr><tr><td><p><code>spec.order</code></p></td><td><p>Optional</p></td><td><p>50</p></td><td><p>The policy read order in the overall policy execution chain.</p></td></tr><tr><td><p><code>spec.rules</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>An array of rules that will determine if the policy applies to a given request. These rules are checked in an OR fashion. The first one to hold will enable applying the policy to the request. The attributes in each rule object apply in an AND fashion. If path and host are defined, both must match for that rule to hold true.</p></td></tr><tr><td><p><code>spec.rules[#].path</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request path.</p><p>Capture groups in this regular expression will be used to define path rewriting when routing the request upstream.</p><p>If "path: /api(/.*)", requests with the path /api/orders will be routed upstream as /orders.</p><p>Multiple capture groups can be specified, and the replacement will be the concatenation of all captured substrings.</p></td></tr><tr><td><p><code>spec.rules[#].host</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request host.</p></td></tr><tr><td><p><code>spec.rules[#].methods</code></p></td><td><p>Optional</p></td><td><p><code>.*</code></p></td><td><p>A regular expression to match the request method.</p></td></tr><tr><td><p><code>spec.rules[#].headers</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A map of header names and value regular expressions that must be present in the request.</p><p>Each entry’s key is the expected header name and the value is a regular expression to match the header value.</p></td></tr></tbody></table>

### Policy Binding Examples

The following resource binds a `route` policy to the API instance, routing traffic specified by the
`rules` to the proxy address specified in the `Service` configuration snippet:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-route namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
policyRef: name: route namespace: default config: destinationRef: name: json namespace: e-commerce
rules:

- path: /api/json(/.\*)

The following resource binds a `http-basic-authentication-flex` policy to the API instance -
requiring requests to include the basic credentials defined in `config.username` and
`config.password`. The policy is given a read order value of `2`.

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
hello-flex-gateway-auth namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance
namespace: e-commerce policyRef: name: http-basic-authentication-flex namespace: default config:
username: chris password: admin order: 2

### Environment Variables for Policy Bindings

Both policy binding resources and inline policy bindings support environment variables in `config`
fields. The environment variables available are dependent on your environment.

To reference your environment variable, specify your environment variable prefixed by `$`, for
example:

\- policyRef: name: http-basic-authentication-flex config: username:
$USERNAME
    password: $PASSWORD

## Service

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: <service name> namespace:
<namespace name> spec: address: <service address including port>

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service identifier.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td></td></tr><tr><td><p><code>spec.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The service address URL, including protocol, host and port. Supported format: <code>protocol://host:port</code>, where <code>protocol</code> is either <code>http</code> or <code>https</code>.</p></td></tr></tbody></table>

### Service Example

The following resource defines a `Service` with metadata that describes the service identifier. The
`metadata.namespace` value matches the namespace specified in the `ApiInstance` configuration. The
`spec.address` is the address of the API implementation:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json-example namespace:
e-commerce spec: address: https://<upstream address>:443/

## Configuration

Define a desired gateway state by creating a `Configuration` entity. `Configuration` entities
specify several runtime configuration aspects for Omni Gateway itself, such as [logging](#logging)
and [shared storage](#shared-storage). The definition includes the following:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: <value> namespace:
<namespace name> spec: logging: # logging configuration sharedStorage: # shared storage
configuration

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>metadata.name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Configuration entity.</p></td></tr><tr><td><p><code>metadata.namespace</code></p></td><td><p>Optional</p></td><td><p><code>default</code></p></td><td><p>The namespace value used to isolate Configuration entities.</p></td></tr><tr><td><p><code>spec</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The configuration object that defines gateway characteristics. Objects include: <code>logging</code>, <code>sharedStorage</code>, <code>tls</code>.</p></td></tr></tbody></table>

### Logging

The `logging` object configures the delivery of runtime and access logs enabled via the message
logging policy. Logs are delivered to any supported Fluent Bit v3.2.10 output.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
      - name: <output-name>
        type: <output-type>
        parameters:
          <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>logging.outputs[#].name</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The name of this output to later refer to in runtime and access logs configurations.</p></td></tr><tr><td><p><code>logging.outputs[#].type</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>An output type supported by Fluent Bit. For Fluent Bit output types, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.outputs[#].parameters</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see <a href="https://docs.fluentbit.io/manual">Fluent Bit documentation</a> for your Fluent Bit version.</p></td></tr><tr><td><p><code>logging.accessLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect access logs to.</p></td></tr><tr><td><p><code>logging.runtimeLogs.logLevel</code></p></td><td><p>Optional</p></td><td><p><code>info</code></p></td><td><p>A parameter specifying log detail. The supported <code>logLevel</code> types listed in decreasing verbosity are <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>fatal</code>.</p></td></tr><tr><td><p><code>logging.runtimeLogs.outputs</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>A list of output names to redirect runtime logs to.</p></td></tr></tbody></table>

Leaving a value blank applies the default value to your configuration.

In addition to parameters above, Omni Gateway offers variables for logging output. When configured,
the variables render as one of their respective outputs in the logs:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Outputs</th></tr></thead><tbody><tr><td><p><code>date</code></p></td><td><p>Date and time of the logged event</p></td><td><p>A specific time, for example, <code>17/11/2022-09:48:27AM</code></p></td></tr><tr><td><p><code>logger</code></p></td><td><p>Omni Gateway service where the logged event occurred</p></td><td><p><code>flex-gateway-agent</code>, <code>flex-gateway-envoy</code>, and <code>flex-gateway-fluent</code></p></td></tr><tr><td><p><code>level</code></p></td><td><p><code>Loglevel</code> of the logged event</p></td><td><p><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, or <code>fatal</code></p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Log type</p></td><td><p><code>runtimeLog</code> or <code>accessLog</code></p></td></tr></tbody></table>

#### Logging Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: logging spec: logging:
outputs: - name: log-to-file type: file parameters: path: /var/log file: log.txt format: template
template: | \[{date}\]\[{logger}\]\[{level}\]\[{kind}\] {message} runtimeLogs: logLevel: info
outputs: - log-to-file accessLogs: outputs: - log-to-file

### Shared Storage

The `sharedStorage` object configures the gateway for shared storage. Omni Gateway supports three
types of shared storage:

- **Distributed shared storage**: Enables multiple gateway replicas to share state across a
  distributed deployment. Data is lost when all replicas go down (scaled to zero replicas).

- **Redis shared storage**: Provides persistent storage when all replicas go down (scaled to zero
  replicas). Requires [Redis](https://redis.io/) (minimum version 4.0.0).

- **Local shared storage**: File-based implementation. Data is persisted to disk, so it is retained
  when Omni Gateway is stopped or restarted. This is the default when no `sharedStorage`
  configuration is provided.

Optionally, you can use Redis with Transport Layer Security (TLS) to protect sensitive data, prevent
unauthorized access, and maintain the reliability of your services.

#### Distributed Shared Storage

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: api-shared-storage
spec: sharedStorage: objectStore: url: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>sharedStorage.objectStore.url</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The distributed shared storage URL in the format <code>distributed://&lt;bind-address&gt;:&lt;port&gt;?join=&lt;host1&gt;:&lt;port1&gt;,&lt;host2&gt;:&lt;port2&gt;,…​</code></p></td></tr></tbody></table>

#### Redis Shared Storage

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: shared-storage-redis
spec: sharedStorage: redis: address: <string> // REQUIRED username: <string> // OPTIONAL password:
<string> // OPTIONAL db: <string> // OPTIONAL tls: // OPTIONAL trustedCA: <string> // OPTIONAL
certificate: // OPTIONAL keyPassphrase <string> // OPTIONAL key: <string> // REQUIRED crt: <string>
// REQUIRED alpn: <array> // OPTIONAL skipValidation: <boolean> // OPTIONAL minversion: <string> //
OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>sharedStorage.redis.address</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The Redis instance address in <code>host:port</code> format</p></td></tr><tr><td><p><code>sharedStorage.redis.username</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user name</p></td></tr><tr><td><p><code>sharedStorage.redis.password</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis user password</p></td></tr><tr><td><p><code>sharedStorage.redis.db</code></p></td><td><p>Optional</p></td><td><p>0</p></td><td><p>The Redis database number to use</p></td></tr><tr><td><p><code>sharedStorage.redis.tls</code></p></td><td><p>Optional</p></td><td><p>Empty</p></td><td><p>The Redis TLS configuration</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.trustedCA</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Root certificate authority to use when verifying server certificates</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate</code></p></td><td><p>Optional</p></td><td><p>N/A</p></td><td><p>Client certificate to present to the server</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.keyPassphrase</code></p></td><td><p>Optional</p></td><td><p><code>none</code></p></td><td><p>The certificate key passphrase. If specified, use the private key format that includes a DEK-Info header. If unspecified, the private key must not be encrypted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.key</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The private key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.certificate.crt</code></p></td><td><p>Required</p></td><td><p>N/A</p></td><td><p>The public key part of the certificate</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.skipValidation</code></p></td><td><p>Optional</p></td><td><p><code>false</code></p></td><td><p>If true, any certificate presented by the server is accepted.</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.minversion</code></p></td><td><p>Optional</p></td><td><p><code>1.2</code></p></td><td><p>The minimum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.maxversion</code></p></td><td><p>Optional</p></td><td><p><code>1.3</code></p></td><td><p>The maximum TLS version allowed</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.alpn</code></p></td><td><p>Optional</p></td><td><p>Empty list</p></td><td><p>A prioritized list of supported application level protocols; for example, h2, http/1.1</p></td></tr><tr><td><p><code>sharedStorage.redis.tls.ciphers</code></p></td><td><p>Optional</p></td><td></td><td></td></tr></tbody></table>

> [!NOTE] TLS/Redis supports the same ciphers as the [TLS policy](https://docs.mulesoft.com/gateway/latest/policies-included-tls), except the
> following:
>
> - TLS\_RSA\_WITH\_NULL\_SHA
>
> - TLS\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_128\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_AES\_256\_CBC\_SHA
>
> - TLS\_ECDHE\_PSK\_WITH\_CHACHA20\_POLY1305\_SHA256

**Redis Shared Storage Example**

The Redis storage service is an implementation of a REST API object store that functions as a bridge
between the object store interface and a Redis backend.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis.e-commerce.svc:6379
      username: ecomm-user
      password: ecomm-pwd-123
      DB: 7
```

**Redis with TLS Shared Storage Example**

Optionally, you can use Redis with TLS to protect data and ensure secure communication.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
```

**Distributed Shared Storage Example**

Distributed shared storage enables multiple gateway replicas to share state across a distributed
deployment.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: api-shared-storage
spec:
  sharedStorage:
    objectStore:
      url: distributed://0.0.0.0:30001?join=flex.hostname.com:30001
```

> [!NOTE] You can specify multiple host names in the `join` parameter by separating them with
> commas. For example:
> `distributed://0.0.0.0:30001?join=node1.example.com:30001,node2.example.com:30001,192.168.1.10:30001`.
> The hostname must resolve to the IPs of the Omni Gateway replicas. Firewall rules must allow Omni
> Gateway replicas to create connections between each other on port 30001.

**Local Shared Storage Example**

The local storage service is an implementation of a REST API object store that saves data to disk.
Data is persisted, so it is retained when Omni Gateway is stopped or restarted. Local shared storage
is the default when no `sharedStorage` configuration is provided.

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: rtm-config
  namespace: sales
spec:
  sharedStorage:
    local:
      enabled: true
```

## Examples

### Inline Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: api-example spec:
address: http://0.0.0.0:8080 services: api-example: address: https://<your url>:443/ routes: -
rules: - path: /api(/users/.\*) - path: /api(/comments/.\*) config: destinationPath: /v1/apps
policies: - policyRef: name: http-basic-authentication-flex config: username: chris password: admin

### Resource-Based Configuration Example

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec:
address: http://0.0.0.0:8080
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json spec: address: https://<your url>:443/
---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-route
spec: targetRef: name: ingress-http policyRef: name: route config: destinationRef: name: json rules:

- path: /api(/users/.\*)
- path: /api(/comments/.\*)

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
ingress-http-authentication spec: targetRef: name: ingress-http policyRef: name:
http-basic-authentication-flex config: username: chris password: admin

<!-- document id=d8c8a65f6c1d08a95eb1196474480671a39ad4ed9fa02fcec950e3ecde628f6f url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-delete.md -->

---
product: Omni Gateway
version: 1.12
---

# Delete an Instance of Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To delete a gateway and its replicas in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the action menu button for the gateway that you want to delete.

4.  Click **Delete gateway**.

If there are APIs associated with the gateway you want to delete, Runtime Manager displays a message
that prompts you to either:

- Move the associated APIs to another gateway.

- Delete all associated APIs.

Once you moved or deleted all the associated APIs, follow the steps previously described to delete a
gateway and confirm the deletion.

## Flex Gateway Status

The following table describes the meaning of each gateway status:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status Name</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>Gateway is connected to the platform, and you can add APIs to it.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>Gateway is not connected to the platform.</p></div></div></td></tr><tr><td><div><div><p>Deleting</p></div></div></td><td><div><div><p>Gateway is in the process of being deleted.</p></div></div></td></tr><tr><td><div><div><p>Deleted</p></div></div></td><td><div><div><p>Gateway was deleted from the platform. It stops accepting API requests and configuration changes, and stops reporting metrics.</p></div></div></td></tr></tbody></table>

Deleted gateways are shown with status `Deleted` for 30 days before the status is removed from the
gateways list.

> [!NOTE] If you delete a gateway, you lose its configuration history and can’t recover it.

<!-- document id=7c44e4eef0bc55be7a81b86d8a36f1f4cd5b9a4449fe29c8e4d623c4ec2afd71 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-delete.md -->

---
product: Omni Gateway
version: 1.9
---

# Delete an Instance of Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To delete a gateway and its replicas in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the action menu button for the gateway that you want to delete.

4.  Click **Delete gateway**.

If there are APIs associated with the gateway you want to delete, Runtime Manager displays a message
that prompts you to either:

- Move the associated APIs to another gateway.

- Delete all associated APIs.

Once you moved or deleted all the associated APIs, follow the steps previously described to delete a
gateway and confirm the deletion.

## Flex Gateway Status

The following table describes the meaning of each gateway status:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status Name</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>Gateway is connected to the platform, and you can add APIs to it.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>Gateway is not connected to the platform.</p></div></div></td></tr><tr><td><div><div><p>Deleting</p></div></div></td><td><div><div><p>Gateway is in the process of being deleted.</p></div></div></td></tr><tr><td><div><div><p>Deleted</p></div></div></td><td><div><div><p>Gateway was deleted from the platform. It stops accepting API requests and configuration changes, and stops reporting metrics.</p></div></div></td></tr></tbody></table>

Deleted gateways are shown with status `Deleted` for 30 days before the status is removed from the
gateways list.

> [!NOTE] If you delete a gateway, you lose its configuration history and can’t recover it.

<!-- document id=83a1f0a116f1311ecd890f73760fd0a538fffbc58bb05524f4d4cbfea3d95bcc url=/mulesoft/current/en-us/gateway/1.13/gateway-delete.md -->

---
product: Omni Gateway
version: 1.13
---

# Delete an Instance of Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To delete a gateway and its replicas in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the action menu button for the gateway that you want to delete.

4.  Click **Delete gateway**.

If there are APIs associated with the gateway you want to delete, Runtime Manager displays a message
that prompts you to either:

- Move the associated APIs to another gateway.

- Delete all associated APIs.

Once you moved or deleted all the associated APIs, follow the steps previously described to delete a
gateway and confirm the deletion.

## Omni Gateway Status

The following table describes the meaning of each gateway status:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status Name</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>Gateway is connected to the platform, and you can add APIs to it.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>Gateway is not connected to the platform.</p></div></div></td></tr><tr><td><div><div><p>Deleting</p></div></div></td><td><div><div><p>Gateway is in the process of being deleted.</p></div></div></td></tr><tr><td><div><div><p>Deleted</p></div></div></td><td><div><div><p>Gateway was deleted from the platform. It stops accepting API requests and configuration changes, and stops reporting metrics.</p></div></div></td></tr></tbody></table>

Deleted gateways are shown with status `Deleted` for 30 days before the status is removed from the
gateways list.

> [!NOTE] If you delete a gateway, you lose its configuration history and can’t recover it.

<!-- document id=c2ee5f1193d9357c5280dc21ed7ac0734b1bc835c0e0091011c1595fbbaf248a url=/mulesoft/current/en-us/gateway/latest/gateway-delete.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Delete an Instance of Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To delete a gateway and its replicas in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the action menu button for the gateway that you want to delete.

4.  Click **Delete gateway**.

If there are APIs associated with the gateway you want to delete, Runtime Manager displays a message
that prompts you to either:

- Move the associated APIs to another gateway.

- Delete all associated APIs.

Once you moved or deleted all the associated APIs, follow the steps previously described to delete a
gateway and confirm the deletion.

## Omni Gateway Status

The following table describes the meaning of each gateway status:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status Name</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>Gateway is connected to the platform, and you can add APIs to it.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>Gateway is not connected to the platform.</p></div></div></td></tr><tr><td><div><div><p>Deleting</p></div></div></td><td><div><div><p>Gateway is in the process of being deleted.</p></div></div></td></tr><tr><td><div><div><p>Deleted</p></div></div></td><td><div><div><p>Gateway was deleted from the platform. It stops accepting API requests and configuration changes, and stops reporting metrics.</p></div></div></td></tr></tbody></table>

Deleted gateways are shown with status `Deleted` for 30 days before the status is removed from the
gateways list.

> [!NOTE] If you delete a gateway, you lose its configuration history and can’t recover it.

<!-- document id=f32e9e126d3514f45827f8ff33cc2306ca37eef43c69c812aa59ab03fcc8776f url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-managed-set-up.md -->

---
product: Omni Gateway
version: 1.12
---

# Deploy a Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Deploy a Managed Flex Gateway to a CloudHub 2.0 private space or Runtime Fabric namespace to launch
a completely managed gateway. Configure the Managed Flex Gateway as an ingress to your target space
by exposing a public endpoint, or configure the gateway to only handle internal traffic. You can
have one or more Managed Gateway in each environment that the target space is shared with. Gateways
can protect any instance from the same environment of the gateway or services in an external
network.

## Before You Begin

### CloudHub 2.0

Before getting started with Flex Gateway on CloudHub 2.0, make sure:

- The business group you want to deploy your gateway to has Managed Flex Gateway Resources. To
  redestribute Managed Flex Gateway resources to a business group, see
  [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

  > [!NOTE] Gateways cannot be shared across business groups. A user must be a member of the
  > business group to access the Flex Gateway.

- [Create a CloudHub 2.0 Private Space](https://docs.mulesoft.com/cloudhub-2/ps-create-configure)

### Runtime Fabric

Before getting started with Flex Gateway on Runtime Fabric, make sure:

- Your Runtime Fabric deployment version is 2.11.0 or later. To upgrade, see
  [Upgrading Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/latest/upgrade-index).

- The business group you want to deploy your gateway to has Managed Flex Gateway Resources. To
  redestribute Managed Flex Gateway resources to a business group, see
  [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

  > [!NOTE] Gateways cannot be shared across business groups. A user must be a member of the
  > business group to access the Flex Gateway.

- Run this command in the same namespace as your Runtime Fabric agent to enable the
  `ManagedFlexGateway` resource:

  ```bash
  # When performing the helm upgrade for the first time, during Runtime Fabric creation:
  helm upgrade runtime-fabric rtf/rtf-agent -n <rtf-agent-namespace> --version <target-rtf-version> --set global.crds.flex.enabled=true

  # When enabling Managed Flex Gateway for an existing runtime fabric:
  helm upgrade runtime-fabric rtf/rtf-agent -n <rtf-agent-namespace> --reset-then-reuse-values --set global.crds.flex.enabled=true
  ```

> [!NOTE] For Flex Gateway Agent Fabric deployments on Runtime Fabric, you must enable Open
> Telemetry with a `100` percent **Sampling percentage**. You can’t override the sampling percentage
> for individual instances.

## Deploy a Managed Flex Gateway

1.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

2.  Select **Runtime Manager**.

3.  Ensure you’re in environment where you would like to deploy your Managed Gateway

4.  Click **Flex Gateways** in the side navigation panel.

5.  Click **Managed Flex Gateway**.

6.  Click **Add Managed Flex Gateway**.

7.  Enter a **Gateway Name**.

8.  Select the **Deployment Target** where you want to deploy your Managed Flex Gateway.

9.  Select a **Release Channel**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Release channel</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;every four months. It has the latest features and shorter support windows.</p></div></div></td></tr><tr><td><div><div><p><strong>Long-Term Support</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;once a year.</p></div></div></td></tr></tbody></table>

    To learn more about the differences between release channels, see
    [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.12/flex-gateway-version-lifecycle).

10. Select **Version**.

    Select the latest version unless if a later version is specifically needed.

11. Select **Gateway type**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Size</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Small Managed Flex Gateway</strong></p></div></div></td><td><div><div><p>Use for testing and staging purposes. Small Managed Flex Gateways can deploy up to 50 APIs.</p></div></div></td></tr><tr><td><div><div><p><strong>Large Managed Flex Gateway</strong></p></div></div></td><td><div><div><p>Use for production purposes. Large Managed Flex Gateways can deploy up to 500 APIs.</p></div></div></td></tr><tr><td><div><div><p><strong>Extra Large Managed Flex Gateway</strong></p></div></div></td><td><div><div><p>Use for production purposes with higher throughput and more process demanding policies. Extra Large Managed Flex Gateways can deploy up to 500 APIs.</p></div></div></td></tr></tbody></table>

    To learn more about Managed Flex Gateway sizing, see
    [Managed Flex Gateway Limits](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites#managed-flex-gateway-limits).

12. Configure **Advanced options**:

    Ingress

    - **Public endpoint**:

      1.  Select your desired private space **Domain**.

          To learn more, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

      2.  Enter a **Host**.

      3.  Click **Add Endpoint** to add an additional endpoint to a different domain.

          Managed Flex Gateway supports one **Public endpoint** per domain in your private space.

    - **Ingress options**:

      - **Forward SSL Session**:

        Enables SSL forwarding during a session.

        SSL forwarding is mostly used with client authentication. See
        [Enable Client Authentication](https://docs.mulesoft.com/anypoint-security/enable-client-authentication). SSL
        forwarding forwards client certificate details in HTTP request headers so they are available
        to the gateway. These fields can identify an authenticated client and allow the gateway
        policies to determine and use the identity.

        The following headers are available:

        <table><colgroup><col> <col></colgroup><thead><tr><th>Header Name</th><th>Value</th></tr></thead><tbody><tr><td><div><div><p>x-ssl-client-verify</p></div></div></td><td><div><div><p>SUCCESS/FAIL</p></div></div></td></tr><tr><td><div><div><p>x-ssl-issuer</p></div></div></td><td><div><div><p>Client certificate issuer</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-serial</p></div></div></td><td><div><div><p>Client certificate serial number</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-dn</p></div></div></td><td><div><div><p>Contents of the client certificate DN field</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-cert</p></div></div></td><td><div><div><p>Contents of the client certificate</p></div></div></td></tr></tbody></table>

      - **Last-mile Security**:

        Specifies that TLS termination and decryption for the forwarded HTTPS connections occurs in
        the gateway.

    Properties

    To configure how long Managed Flex Gateway waits for response or idle connections, configure the
    timeout properties:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Parameter</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Connection Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a upstream connection can remain idle without receiving client requests. Upstream responses are not included in this timeout.</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Response Timeout</strong></p></div></div></td><td><div><div><p>The time the upstream service has to respond from when Flex Gateway sends a request.</p></div></div></td></tr><tr><td><div><div><p><strong>Stream Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a stream can remain idle without receiving additional client requests or upstream responses.</p></div></div></td></tr></tbody></table>

    You can also update timeout values later from **Runtime Configurations** in Runtime Manager. For
    details, see [Configure Timeouts for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-timeout).

    Logging

    - **Forward application logs to Anypoint Monitoring**:

      Forwards Flex Gateway logs to Anypoint Monitoring. When disabled, logs are only available in
      Runtime Manager.

    - **Additional Log Levels**:

      - **INFO**: Informative messages

      - **DEBUG**: Debugging messages

      - **WARNING**: Warning messages

      - **ERROR**: Error messages, such as when an exception occurs

      - **FATAL**: Fatal messages for when an application fails

        > [!NOTE] You can use Access Management audit logs to track Managed Flex Gateway actions,
        > such as creating, editing, starting, and stopping gateways. Audit logs don't require
        > configuration.
        >
        > To learn more, see xref:flex-managed-view-status.adoc#audit-logs\[View Managed Flex
        > Gateway Audit Logs\].

    Distributed Tracing

    - **Distributed tracing**:

      Enable to generate OpenTelemetry distributed tracing data for the Managed Flex Gateway. When
      enabled, you can set the sampling percentage.

    - **Sampling percentage**:

      Set the overall distributed tracing sampling percentage. This setting corresponds to the
      `overall` sampling percentage. The `client` and `random` sampling percentages are set to 100%
      by default, if the sampling percentage is set to a non-zero value here.

      Set the **Sampling percentage** to 0 if you want to specify the sampling percentage only on a
      per-API basis, using the Tracing policy.

      > [!NOTE] For Flex Gateway Agent Fabric deployments on Runtime Fabric, you must enable Open
      > Telemetry with a `100` percent **Sampling percentage**. You cannot override the sampling
      > percentage for individual instances.

13. Click **Save & deploy**.

## Edit a Managed Flex Gateway Settings

To edit a Managed Flex Gateway setting:

1.  From Anypoint Platform, select **Runtime Manager > Flex Gateways**.

2.  Click the Managed Flex Gateway name.

3.  In the navigation menu, click Settings.

4.  Make the necessary edits.

5.  Click **Apply changes**.

## Remove an Endpoint

To remove an endpoint:

1.  From Anypoint Platform, select **Runtime Manager > Flex Gateways**.

2.  Click the Managed Flex Gateway name.

3.  In the navigation menu, click Settings.

4.  Click **Advanced options**.

5.  In the **Public endpoint** row, click **X** (Delete).

6.  Click **Apply changes**.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

<!-- document id=45082b55ec6509887c16222013575fd10d6bd68129c50709e74aca41bf2ccbd0 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-managed-set-up.md -->

---
product: Omni Gateway
version: 1.9
---

# Deploy a Managed Flex Gateway to CloudHub 2.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Deploy a Managed Flex Gateway to a CloudHub 2.0 private space to launch a completely cloud hosted
gateway. Configure the Managed Flex Gateway as an ingress to you private space by exposing a public
endpoint, or configure the gateway to only handle internal traffic. You can have one or more Managed
Gateway in each environment that the private space is shared with. Gateways can protect any API from
the same environment of the gateway or APIs in an external network.

## Before You Begin

Before getting started with Flex Gateway, ensure:

- The business group you want to deploy your gateway to has Managed Flex Gateway Resources. To
  redestribute Managed Flex Gateway resources to a business group, see
  [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

- You have created a private space in CloudHub 2.0 or have access to a private space created by
  someone else. To create a private space, see
  [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Deploy a Managed Flex Gateway

1.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

2.  Select **Runtime Manager**.

3.  Ensure you’re in environment where you would like to deploy your Managed Gateway

4.  Click **Flex Gateways** in the side navigation panel.

5.  Click **Managed Flex Gateway**.

6.  Click **Add Managed Flex Gateway**.

7.  Enter a **Gateway Name**.

8.  Select the private space where you want to deploy your Managed Flex Gateway as your **Deployment
    Target**.

9.  Select a **Release Channel**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Release channel</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;every four months. It has the latest features and shorter support windows.</p></div></div></td></tr><tr><td><div><div><p><strong>Long-Term Support</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;once a year.</p></div></div></td></tr></tbody></table>

    To learn more about the differences between release channels, see
    [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.9/flex-gateway-version-lifecycle).

10. Select **Version**.

    Select the latest version unless if a later version is specifically needed.

11. Select **Flow Plans**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Size</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Small Managed Flex Gateway</strong></p></div></div></td><td><div><div><p>Use for testing and staging purposes. Small Managed Flex Gateways can deploy up to 50 APIs with a maximum of 100 requests per second.</p></div></div></td></tr><tr><td><div><div><p><strong>Large Managed Flex Gateway</strong></p></div></div></td><td><div><div><p>Use for production purposes. Large Managed Flex Gateways can deploy up to 500 APIs with a maximum of 500 requests per second.</p></div></div></td></tr></tbody></table>

    To learn more about Managed Flex Gateway sizing, see
    [Managed Flex Gateway Limits](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites#managed-flex-gateway-limits).

12. Configure **Advanced options**:

    Ingress

    - **Public endpoint**:

      1.  Select your desired private space **Domain**.

          To learn more, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

      2.  Enter a **Host**.

      3.  Click **Add Endpoint** to add an additional endpoint to a different domain.

          Managed Flex Gateway supports one **Public endpoint** per domain in your private space.

    - **Ingress options**:

      - **Forward SSL Session**:

        Enables SSL forwarding during a session.

        SSL forwarding is mostly used with client authentication. See
        [Enable Client Authentication](https://docs.mulesoft.com/anypoint-security/enable-client-authentication). SSL
        forwarding forwards client certificate details in HTTP request headers so they are available
        to the gateway. These fields can identify an authenticated client and allow the gateway
        policies to determine and use the identity.

        The following headers are available:

        <table><colgroup><col> <col></colgroup><thead><tr><th>Header Name</th><th>Value</th></tr></thead><tbody><tr><td><div><div><p>x-ssl-client-verify</p></div></div></td><td><div><div><p>SUCCESS/FAIL</p></div></div></td></tr><tr><td><div><div><p>x-ssl-issuer</p></div></div></td><td><div><div><p>Client certificate issuer</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-serial</p></div></div></td><td><div><div><p>Client certificate serial number</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-dn</p></div></div></td><td><div><div><p>Contents of the client certificate DN field</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-cert</p></div></div></td><td><div><div><p>Contents of the client certificate</p></div></div></td></tr></tbody></table>

      - **Last-mile Security**:

        Specifies that TLS termination and decryption for the forwarded HTTPS connections occurs in
        the gateway.

    Properties

    To configure how long Managed Flex Gateway waits for response or idle connections, configure the
    timeout properties:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Parameter</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Connection Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a upstream connection can remain idle without receiving client requests. Upstream responses are not included in this timeout.</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Response Timeout</strong></p></div></div></td><td><div><div><p>The time the upstream service has to respond from when Flex Gateway sends a request.</p></div></div></td></tr><tr><td><div><div><p><strong>Stream Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a stream can remain idle without receiving additional client requests or upstream responses.</p></div></div></td></tr></tbody></table>

    Logging

    - **Forward application logs to Anypoint Monitoring**:

      Forwards Flex Gateway logs to Anypoint Monitoring. When disabled, logs are only available in
      Runtime Manager.

    - **Additional Log Levels**:

      - **INFO**: Informative messages

      - **DEBUG**: Debugging messages

      - **WARNING**: Warning messages

      - **ERROR**: Error messages, such as when an exception occurs

      - **FATAL**: Fatal messages for when an application fails

13. Click **Save & deploy**.

## Edit a Managed Flex Gateway Settings

To edit a Managed Flex Gateway settings:

1.  From Anypoint Platform, select **Runtime Manager > Flex Gateways**.

2.  Click the Managed Flex Gateway name.

3.  In the navigation menu, click Settings.

4.  Make the necessary edits.

5.  Click **Apply changes**.

## Remove an Endpoint

To remove an endpoint:

1.  From Anypoint Platform, select **Runtime Manager > Flex Gateways**.

2.  Click the Managed Flex Gateway name.

3.  In the navigation menu, click Settings.

4.  Click **Advanced options**.

5.  In the **Public endpoint** row, click **X** (Delete).

6.  Click **Apply changes**.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up)

<!-- document id=715b847e017a312cd9ecb3f56263029ff4af6c69881c92291f690e542e939208 url=/mulesoft/current/en-us/gateway/1.13/gateway-managed-set-up.md -->

---
product: Omni Gateway
version: 1.13
---

# Deploy a Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Deploy a Managed Omni Gateway to CloudHub 2.0 or a Runtime Fabric namespace to launch a completely
managed gateway.

## Before You Begin

### CloudHub 2.0

Before getting started with Omni Gateway on CloudHub 2.0, make sure:

- The business group you want to deploy your gateway to has Managed Omni Gateway Resources. To
  redestribute Managed Omni Gateway resources to a business group, see
  [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

- [Create a CloudHub 2.0 Private Space](https://docs.mulesoft.com/cloudhub-2/ps-create-configure)

### Runtime Fabric

Before getting started with Omni Gateway on Runtime Fabric, make sure:

- Your Runtime Fabric deployment version is 2.11.0 or later. To upgrade, see
  [Upgrading Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/latest/upgrade-index).

- The business group you want to deploy your gateway to has Managed Omni Gateway Resources. To
  redestribute Managed Omni Gateway resources to a business group, see
  [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

  > [!NOTE] Gateways cannot be shared across business groups. A user must be a member of the
  > business group to access the Omni Gateway.

- Run this command in the same namespace as your Runtime Fabric agent to enable the
  `ManagedFlexGateway` resource:

  ```bash
  # When performing the helm upgrade for the first time, during Runtime Fabric creation:
  helm upgrade runtime-fabric rtf/rtf-agent -n <rtf-agent-namespace> --version <target-rtf-version> --set global.crds.flex.enabled=true

  # When enabling Managed Flex Gateway for an existing runtime fabric:
  helm upgrade runtime-fabric rtf/rtf-agent -n <rtf-agent-namespace> --reset-then-reuse-values --set global.crds.flex.enabled=true
  ```

> [!NOTE] For Omni Gateway Agent Fabric deployments on Runtime Fabric, you must enable Open
> Telemetry with a `100` percent **Sampling percentage**. You can’t override the sampling percentage
> for individual instances.

## Deploy a Managed Omni Gateway

1.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

2.  Select **Runtime Manager**.

3.  Ensure you’re in environment where you would like to deploy your Managed Gateway

4.  Click **Omni Gateways** in the side navigation panel.

5.  Click **Managed Omni Gateway**.

6.  Click **Add Managed Omni Gateway**.

7.  Enter a **Gateway Name**.

8.  Select the **Deployment Target** where you want to deploy your Managed Omni Gateway.

9.  Select a **Release Channel**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Release channel</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;every four months. It has the latest features and shorter support windows.</p></div></div></td></tr><tr><td><div><div><p><strong>Long-Term Support</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;once a year.</p></div></div></td></tr></tbody></table>

    To learn more about the differences between release channels, see
    [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.13/gateway-version-lifecycle).

10. Select **Version**.

    Select the latest version unless if a later version is specifically needed.

11. Select **Gateway type**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Size</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Small Managed Omni Gateway</strong></p></div></div></td><td><div><div><p>Use for testing and staging purposes. Small Managed Omni Gateways can deploy up to 50 APIs.</p></div></div></td></tr><tr><td><div><div><p><strong>Large Managed Omni Gateway</strong></p></div></div></td><td><div><div><p>Use for production purposes. Large Managed Omni Gateways can deploy up to 500 APIs.</p></div></div></td></tr><tr><td><div><div><p><strong>Extra Large Managed Omni Gateway</strong></p></div></div></td><td><div><div><p>Use for production purposes with higher throughput and more process demanding policies. Extra Large Managed Omni Gateways can deploy up to 500 APIs.</p></div></div></td></tr></tbody></table>

    To learn more about Managed Omni Gateway sizing, see
    [Managed Omni Gateway Limits](https://docs.mulesoft.com/gateway/1.13/review-prerequisites#managed-flex-gateway-limits).

12. Configure **Advanced options**:

    Ingress

    You can’t configure the ingress options for a Managed Omni Gateway deployed to a CloudHub 2.0
    shared space. Shared Spaces don’t support vanity domains.

    - **Public endpoint**:

      1.  Select your desired private space **Domain**.

          To learn more, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

      2.  Enter a **Host**.

      3.  Click **Add Endpoint** to add an additional endpoint to a different domain.

          Managed Omni Gateway supports one **Public endpoint** per domain in your private space.

    - **Ingress options**:

      - **Forward SSL Session**:

        Enables SSL forwarding during a session.

        SSL forwarding is mostly used with client authentication. See
        [Enable Client Authentication](https://docs.mulesoft.com/anypoint-security/enable-client-authentication). SSL
        forwarding forwards client certificate details in HTTP request headers so they are available
        to the gateway. These fields can identify an authenticated client and allow the gateway
        policies to determine and use the identity.

        The following headers are available:

        <table><colgroup><col> <col></colgroup><thead><tr><th>Header Name</th><th>Value</th></tr></thead><tbody><tr><td><div><div><p>x-ssl-client-verify</p></div></div></td><td><div><div><p>SUCCESS/FAIL</p></div></div></td></tr><tr><td><div><div><p>x-ssl-issuer</p></div></div></td><td><div><div><p>Client certificate issuer</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-serial</p></div></div></td><td><div><div><p>Client certificate serial number</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-dn</p></div></div></td><td><div><div><p>Contents of the client certificate DN field</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-cert</p></div></div></td><td><div><div><p>Contents of the client certificate</p></div></div></td></tr></tbody></table>

      - **Last-mile Security**:

        Specifies that TLS termination and decryption for the forwarded HTTPS connections occurs in
        the gateway.

    Properties

    To configure how long Managed Omni Gateway waits for response or idle connections, configure the
    timeout properties:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Parameter</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Connection Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a upstream connection can remain idle without receiving client requests. Upstream responses are not included in this timeout.</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Response Timeout</strong></p></div></div></td><td><div><div><p>The time the upstream service has to respond from when Omni Gateway sends a request.</p></div></div></td></tr><tr><td><div><div><p><strong>Stream Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a stream can remain idle without receiving additional client requests or upstream responses.</p></div></div></td></tr></tbody></table>

    You can also update timeout values later from **Runtime Configurations** in Runtime Manager. For
    details, see [Configure Timeouts for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-timeout).

    Logging

    - **Forward application logs to Anypoint Monitoring**:

      Forwards Omni Gateway logs to Anypoint Monitoring. When disabled, logs are only available in
      Runtime Manager.

    - **Additional Log Levels**:

      - **INFO**: Informative messages

      - **DEBUG**: Debugging messages

      - **WARNING**: Warning messages

      - **ERROR**: Error messages, such as when an exception occurs

      - **FATAL**: Fatal messages for when an application fails

        > [!NOTE] You can use Access Management audit logs to track Managed Omni Gateway actions,
        > such as creating, editing, starting, and stopping gateways. Audit logs don't require
        > configuration.
        >
        > To learn more, see xref:managed-view-status.adoc#audit-logs\[View Managed Omni Gateway
        > Audit Logs\].

    Distributed Tracing

    - **Distributed tracing**:

      Enable to generate OpenTelemetry distributed tracing data for the Managed Omni Gateway. When
      enabled, you can set the sampling percentage.

    - **Sampling percentage**:

      Set the overall distributed tracing sampling percentage. This setting corresponds to the
      `overall` sampling percentage. The `client` and `random` sampling percentages are set to 100%
      by default, if the sampling percentage is set to a non-zero value here.

      Set the **Sampling percentage** to 0 if you want to specify the sampling percentage only on a
      per-API basis, using the Tracing policy.

      > [!NOTE] For Omni Gateway Agent Fabric deployments on Runtime Fabric, you must enable Open
      > Telemetry with a `100` percent **Sampling percentage**. You cannot override the sampling
      > percentage for individual instances.

13. Click **Save & deploy**.

## Managed Omni Gateway Endpoints

Omni Gateway provides these endpoints:

- **Public Endpoint**: The public endpoint is exposed to the public internet. Traffic comes from the
  internet through the CloudHub 2.0 load balancer.

- **Internal Endpoint**: The internal endpoint is not publicly exposed on the internet, but traffic
  still goes through the CloudHub 2.0 load balancer for internal traffic within the private space.
  Use an internal endpoint when you don’t know if traffic comes from inside the cluster or from a
  connected network. This is only available for Managed Omni Gateways deployed to a CloudHub 2.0
  Private Space.

- **Cluster Endpoint**: Only accessible from inside the cluster. Use when the gateway is acting as
  an egress gateway receiving traffic from internal apps. Port 8082 is reserved for cluster endpoint
  traffic.

To find the endpoint names:

1.  From Anypoint Platform, select **Runtime Manager > Omni Gateways**.

2.  Click the Managed Omni Gateway name.

3.  Copy your endpoint from the dashboard.

## Edit a Managed Omni Gateway Settings

To edit a Managed Omni Gateway setting:

1.  From Anypoint Platform, select **Runtime Manager > Omni Gateways**.

2.  Click the Managed Omni Gateway name.

3.  In the navigation menu, click Settings.

4.  Make the necessary edits.

5.  Click **Apply changes**.

## Remove a Public Endpoint

To remove an endpoint:

1.  From Anypoint Platform, select **Runtime Manager > Omni Gateways**.

2.  Click the Managed Omni Gateway name.

3.  In the navigation menu, click Settings.

4.  Click **Advanced options**.

5.  In the **Public endpoint** row, click **X** (Delete).

6.  Click **Apply changes**.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

<!-- document id=cae4f7ab7c81f4ba197c7fda5a046586c615de89ba619a574e266479fd0dad73 url=/mulesoft/current/en-us/gateway/latest/gateway-managed-set-up.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Deploy a Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Deploy a Managed Omni Gateway to CloudHub 2.0 or a Runtime Fabric namespace to launch a completely
managed gateway.

## Before You Begin

### CloudHub 2.0

Before getting started with Omni Gateway on CloudHub 2.0, make sure:

- The business group you want to deploy your gateway to has Managed Omni Gateway Resources. To
  redestribute Managed Omni Gateway resources to a business group, see
  [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

- [Create a CloudHub 2.0 Private Space](https://docs.mulesoft.com/cloudhub-2/ps-create-configure)

### Runtime Fabric

Before getting started with Omni Gateway on Runtime Fabric, make sure:

- Your Runtime Fabric deployment version is 2.11.0 or later. To upgrade, see
  [Upgrading Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/latest/upgrade-index).

- The business group you want to deploy your gateway to has Managed Omni Gateway Resources. To
  redestribute Managed Omni Gateway resources to a business group, see
  [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

  > [!NOTE] Gateways cannot be shared across business groups. A user must be a member of the
  > business group to access the Omni Gateway.

- Run this command in the same namespace as your Runtime Fabric agent to enable the
  `ManagedFlexGateway` resource:

  ```bash
  # When performing the helm upgrade for the first time, during Runtime Fabric creation:
  helm upgrade runtime-fabric rtf/rtf-agent -n <rtf-agent-namespace> --version <target-rtf-version> --set global.crds.flex.enabled=true

  # When enabling Managed Flex Gateway for an existing runtime fabric:
  helm upgrade runtime-fabric rtf/rtf-agent -n <rtf-agent-namespace> --reset-then-reuse-values --set global.crds.flex.enabled=true
  ```

> [!NOTE] For Omni Gateway Agent Fabric deployments on Runtime Fabric, you must enable Open
> Telemetry with a `100` percent **Sampling percentage**. You can’t override the sampling percentage
> for individual instances.

## Deploy a Managed Omni Gateway

1.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

2.  Select **Runtime Manager**.

3.  Ensure you’re in environment where you would like to deploy your Managed Gateway

4.  Click **Omni Gateways** in the side navigation panel.

5.  Click **Managed Omni Gateway**.

6.  Click **Add Managed Omni Gateway**.

7.  Enter a **Gateway Name**.

8.  Select the **Deployment Target** where you want to deploy your Managed Omni Gateway.

9.  Select a **Release Channel**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Release channel</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;every four months. It has the latest features and shorter support windows.</p></div></div></td></tr><tr><td><div><div><p><strong>Long-Term Support</strong></p></div></div></td><td><div><div><p>This channel releases a new minor version&nbsp;once a year.</p></div></div></td></tr></tbody></table>

    To learn more about the differences between release channels, see
    [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/latest/gateway-version-lifecycle).

10. Select **Version**.

    Select the latest version unless if a later version is specifically needed.

11. Select **Gateway type**:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Size</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Small Managed Omni Gateway</strong></p></div></div></td><td><div><div><p>Use for testing and staging purposes. Small Managed Omni Gateways can deploy up to 50 APIs.</p></div></div></td></tr><tr><td><div><div><p><strong>Large Managed Omni Gateway</strong></p></div></div></td><td><div><div><p>Use for production purposes. Large Managed Omni Gateways can deploy up to 500 APIs.</p></div></div></td></tr><tr><td><div><div><p><strong>Extra Large Managed Omni Gateway</strong></p></div></div></td><td><div><div><p>Use for production purposes with higher throughput and more process demanding policies. Extra Large Managed Omni Gateways can deploy up to 500 APIs.</p></div></div></td></tr></tbody></table>

    To learn more about Managed Omni Gateway sizing, see
    [Managed Omni Gateway Limits](https://docs.mulesoft.com/gateway/latest/review-prerequisites#managed-flex-gateway-limits).

12. Configure **Advanced options**:

    Ingress

    You can’t configure the ingress options for a Managed Omni Gateway deployed to a CloudHub 2.0
    shared space. Shared Spaces don’t support vanity domains.

    - **Public endpoint**:

      1.  Select your desired private space **Domain**.

          To learn more, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

      2.  Enter a **Host**.

      3.  Click **Add Endpoint** to add an additional endpoint to a different domain.

          Managed Omni Gateway supports one **Public endpoint** per domain in your private space.

    - **Ingress options**:

      - **Forward SSL Session**:

        Enables SSL forwarding during a session.

        SSL forwarding is mostly used with client authentication. See
        [Enable Client Authentication](https://docs.mulesoft.com/anypoint-security/enable-client-authentication). SSL
        forwarding forwards client certificate details in HTTP request headers so they are available
        to the gateway. These fields can identify an authenticated client and allow the gateway
        policies to determine and use the identity.

        The following headers are available:

        <table><colgroup><col> <col></colgroup><thead><tr><th>Header Name</th><th>Value</th></tr></thead><tbody><tr><td><div><div><p>x-ssl-client-verify</p></div></div></td><td><div><div><p>SUCCESS/FAIL</p></div></div></td></tr><tr><td><div><div><p>x-ssl-issuer</p></div></div></td><td><div><div><p>Client certificate issuer</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-serial</p></div></div></td><td><div><div><p>Client certificate serial number</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-dn</p></div></div></td><td><div><div><p>Contents of the client certificate DN field</p></div></div></td></tr><tr><td><div><div><p>x-ssl-client-cert</p></div></div></td><td><div><div><p>Contents of the client certificate</p></div></div></td></tr></tbody></table>

      - **Last-mile Security**:

        Specifies that TLS termination and decryption for the forwarded HTTPS connections occurs in
        the gateway.

    Properties

    To configure how long Managed Omni Gateway waits for response or idle connections, configure the
    timeout properties:

    <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p>Parameter</p></div></div></td><td><div><div><p>Description</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Connection Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a upstream connection can remain idle without receiving client requests. Upstream responses are not included in this timeout.</p></div></div></td></tr><tr><td><div><div><p><strong>Upstream Response Timeout</strong></p></div></div></td><td><div><div><p>The time the upstream service has to respond from when Omni Gateway sends a request.</p></div></div></td></tr><tr><td><div><div><p><strong>Stream Idle Timeout</strong></p></div></div></td><td><div><div><p>The time a stream can remain idle without receiving additional client requests or upstream responses.</p></div></div></td></tr></tbody></table>

    You can also update timeout values later from **Runtime Configurations** in Runtime Manager. For
    details, see [Configure Timeouts for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-timeout).

    Logging

    - **Forward application logs to Anypoint Monitoring**:

      Forwards Omni Gateway logs to Anypoint Monitoring. When disabled, logs are only available in
      Runtime Manager.

    - **Additional Log Levels**:

      - **INFO**: Informative messages

      - **DEBUG**: Debugging messages

      - **WARNING**: Warning messages

      - **ERROR**: Error messages, such as when an exception occurs

      - **FATAL**: Fatal messages for when an application fails

        > [!NOTE] You can use Access Management audit logs to track Managed Omni Gateway actions,
        > such as creating, editing, starting, and stopping gateways. Audit logs don't require
        > configuration.
        >
        > To learn more, see xref:managed-view-status.adoc#audit-logs\[View Managed Omni Gateway
        > Audit Logs\].

    Distributed Tracing

    - **Distributed tracing**:

      Enable to generate OpenTelemetry distributed tracing data for the Managed Omni Gateway. When
      enabled, you can set the sampling percentage.

    - **Sampling percentage**:

      Set the overall distributed tracing sampling percentage. This setting corresponds to the
      `overall` sampling percentage. The `client` and `random` sampling percentages are set to 100%
      by default, if the sampling percentage is set to a non-zero value here.

      Set the **Sampling percentage** to 0 if you want to specify the sampling percentage only on a
      per-API basis, using the Tracing policy.

      > [!NOTE] For Omni Gateway Agent Fabric deployments on Runtime Fabric, you must enable Open
      > Telemetry with a `100` percent **Sampling percentage**. You cannot override the sampling
      > percentage for individual instances.

13. Click **Save & deploy**.

## Managed Omni Gateway Endpoints

Omni Gateway provides these endpoints:

- **Public Endpoint**: The public endpoint is exposed to the public internet. Traffic comes from the
  internet through the CloudHub 2.0 load balancer.

- **Internal Endpoint**: The internal endpoint is not publicly exposed on the internet, but traffic
  still goes through the CloudHub 2.0 load balancer for internal traffic within the private space.
  Use an internal endpoint when you don’t know if traffic comes from inside the cluster or from a
  connected network. This is only available for Managed Omni Gateways deployed to a CloudHub 2.0
  Private Space.

- **Cluster Endpoint**: Only accessible from inside the cluster. Use when the gateway is acting as
  an egress gateway receiving traffic from internal apps. Port 8082 is reserved for cluster endpoint
  traffic.

To find the endpoint names:

1.  From Anypoint Platform, select **Runtime Manager > Omni Gateways**.

2.  Click the Managed Omni Gateway name.

3.  Copy your endpoint from the dashboard.

## Edit a Managed Omni Gateway Settings

To edit a Managed Omni Gateway setting:

1.  From Anypoint Platform, select **Runtime Manager > Omni Gateways**.

2.  Click the Managed Omni Gateway name.

3.  In the navigation menu, click Settings.

4.  Make the necessary edits.

5.  Click **Apply changes**.

## Remove a Public Endpoint

To remove an endpoint:

1.  From Anypoint Platform, select **Runtime Manager > Omni Gateways**.

2.  Click the Managed Omni Gateway name.

3.  In the navigation menu, click Settings.

4.  Click **Advanced options**.

5.  In the **Public endpoint** row, click **X** (Delete).

6.  Click **Apply changes**.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

<!-- document id=9c0b87cce47135a416e9fcdf32724b842bab9fc79eb2d5a8b050096542173c32 url=/mulesoft/current/en-us/gateway/1.12/flex-local-deploy-custom-policy.md -->

---
product: Omni Gateway
version: 1.12
---

# Deploying a Custom Policy for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. The following steps demonstrate deploying and applying a custom filter (policy) to an API
running in Local Mode:

1.  Create a configuration YAML file.

2.  Save the file in the Flex Gateway configuration directory.

3.  Create the extension definition.

4.  Encode the custom policy WASM implementation using `base64`.

5.  Link the extension definition to the custom policy WASM binary implementation.

6.  Link the custom policy to an API instance.

7.  Apply the resources to the Flex Gateway instance.

## Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in Local Mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URL. See
  [Publishing a Simple API Instance in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-publish-simple-api) for an example.

- A custom policy implemented and compiled. See
  [Implement a Flex Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.12/policies-custom-flex-implement-rust).

## Deploy a Custom Policy

1.  Create a configuration file called `custom-policy-example.yaml`.

2.  Save the file in the Flex Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

3.  Create the extension definition.

    Copy and paste the following YAML snippet into the new configuration file. The YAML defines the
    configuration and metadata properties for the custom policy:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ```

    - The `metadata.name` value contains the extension name.

    - The `Extension` inherits properties from other defined extensions. For example, `spec.extends`
      specifies that the extension is an `extension-definition`, and that it belongs in the
      `authentication` category (`extension-authentication`).

    - The `spec.properties` values define properties that configure the custom policy instance.

    - The `spec.required` value specifies the required properties.

4.  Encode the custom policy WASM binary implementation using `base64`.

    Encode the custom policy WASM binary implementation by executing the following command:

    ```ssh
    base64 <your-custom-policy-name>.wasm | tr -d '\n\r' > policy
    ```

    The command sends the encoded data to a file called `policy`. In the next step, substitute
    `<WASM_BINARY_IN_BASE64>` with this encoded data.

    > [!NOTE] If you compiled the policy using a target of `wasm32-unknown-unknown`, locate the
    > binary in `./target/wasm32-unknown-unknown/release`.
    >
    > If you compiled the policy using a target of `wasm32-wasi`, locate the binary in
    > `./target/wasm32-wasi/release`.

5.  Link the extension definition to the custom policy WASM binary implementation.

    In `custom-policy-example.yaml`, define another resource that contains the policy
    implementation:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ```

    - The `metadata.name` value contains the policy name, which must be different from the name
      specified in the definition.

    - The `spec.extends` value specifies the resource definition to inherit from. For example,
      `custom-local-example-definition` is the resource previously defined.

    - Substitute the `<WASM_BINARY_IN_BASE64>` value of `spec.properties.implementation.default`
      with the `base64` encoded WASM binary data, generated previously.

      > [!NOTE] You can include the policy definition and implementation in the same `Extension`
      > resource, but this generates a tighter coupling between them. It is therefore recommended to
      > separate the two into different resources.

6.  Link the custom policy to an API instance.

    In `custom-policy-example.yaml`, define another resource that links the policy to an API
    instance:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    - The `metadata.name` value contains the custom policy instance name.

    - The `spec.targetRef.name` value contains the name of the API instance on which to apply the
      custom policy. The API instance must already have been defined and applied.

    - The `spec.policyRef.name` value contains the custom policy implementation to apply.

    - The `spec.config` value contains policy configuration data.

7.  Apply the resources to the Flex Gateway instance.

    The complete `custom-policy-example.yaml` file now contains the following:

    ```yaml
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    Save the file in the Flex Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

A custom policy now applies to an API instance called `ingress-http`.

## See Also

- [Implement a Flex Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.12/policies-custom-flex-implement-rust)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide)

<!-- document id=5188f27b96ea5ba77d56b946cf049452c1157932e7ebbf88a682dcb5c08c6d2c url=/mulesoft/current/en-us/gateway/1.9/flex-local-deploy-custom-policy.md -->

---
product: Omni Gateway
version: 1.9
---

# Deploying a Custom Policy for Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. The following steps demonstrate deploying and applying a custom filter (policy) to an API
running in Local Mode:

1.  Create a configuration YAML file.

2.  Save the file in the Flex Gateway configuration directory.

3.  Create the extension definition.

4.  Encode the custom policy WASM implementation using `base64`.

5.  Link the extension definition to the custom policy WASM binary implementation.

6.  Link the custom policy to an API instance.

7.  Apply the resources to the Flex Gateway instance.

## Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in Local Mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URL. See
  [Publishing a Simple API in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-publish-simple-api) for an example.

- A custom policy implemented and compiled. See
  [Implement a Flex Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.9/policies-custom-flex-implement-rust).

## Deploy a Custom Policy

1.  Create a configuration file called `custom-policy-example.yaml`.

2.  Save the file in the Flex Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

3.  Create the extension definition.

    Copy and paste the following YAML snippet into the new configuration file. The YAML defines the
    configuration and metadata properties for the custom policy:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ```

    - The `metadata.name` value contains the extension name.

    - The `Extension` inherits properties from other defined extensions. For example, `spec.extends`
      specifies that the extension is an `extension-definition`, and that it belongs in the
      `authentication` category (`extension-authentication`).

    - The `spec.properties` values define properties that configure the custom policy instance.

    - The `spec.required` value specifies the required properties.

4.  Encode the custom policy WASM binary implementation using `base64`.

    Encode the custom policy WASM binary implementation by executing the following command:

    ```ssh
    base64 <your-custom-policy-name>.wasm | tr -d '\n\r' > policy
    ```

    The command sends the encoded data to a file called `policy`. In the next step, substitute
    `<WASM_BINARY_IN_BASE64>` with this encoded data.

    > [!NOTE] If you compiled the policy using a target of `wasm32-unknown-unknown`, locate the
    > binary in `./target/wasm32-unknown-unknown/release`.
    >
    > If you compiled the policy using a target of `wasm32-wasi`, locate the binary in
    > `./target/wasm32-wasi/release`.

5.  Link the extension definition to the custom policy WASM binary implementation.

    In `custom-policy-example.yaml`, define another resource that contains the policy
    implementation:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ```

    - The `metadata.name` value contains the policy name, which must be different from the name
      specified in the definition.

    - The `spec.extends` value specifies the resource definition to inherit from. For example,
      `custom-local-example-definition` is the resource previously defined.

    - Substitute the `<WASM_BINARY_IN_BASE64>` value of `spec.properties.implementation.default`
      with the `base64` encoded WASM binary data, generated previously.

      > [!NOTE] You can include the policy definition and implementation in the same `Extension`
      > resource, but this generates a tighter coupling between them. It is therefore recommended to
      > separate the two into different resources.

6.  Link the custom policy to an API instance.

    In `custom-policy-example.yaml`, define another resource that links the policy to an API
    instance:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    - The `metadata.name` value contains the custom policy instance name.

    - The `spec.targetRef.name` value contains the name of the API instance on which to apply the
      custom policy. The API instance must already have been defined and applied.

    - The `spec.policyRef.name` value contains the custom policy implementation to apply.

    - The `spec.config` value contains policy configuration data.

7.  Apply the resources to the Flex Gateway instance.

    The complete `custom-policy-example.yaml` file now contains the following:

    ```yaml
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    Save the file in the Flex Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

A custom policy now applies to an API instance called `ingress-http`.

## See Also

- [Implement a Flex Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.9/policies-custom-flex-implement-rust)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide)

<!-- document id=1d1efb07ed867b887199f2a30ae42c7da2101420e77a71e54bd8bc6057848248 url=/mulesoft/current/en-us/gateway/1.13/local-deploy-custom-policy.md -->

---
product: Omni Gateway
version: 1.13
---

# Deploying a Custom Policy for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. The following steps demonstrate deploying and applying a custom filter (policy) to an API
running in Local Mode:

1.  Create a configuration YAML file.

2.  Save the file in the Omni Gateway configuration directory.

3.  Create the extension definition.

4.  Encode the custom policy WASM implementation using `base64`.

5.  Link the extension definition to the custom policy WASM binary implementation.

6.  Link the custom policy to an API instance.

7.  Apply the resources to the Omni Gateway instance.

## Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in Local Mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more
  information about installing and running the gateway.

- Your upstream service URL. See
  [Publishing a Simple API Instance in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-publish-simple-api) for an example.

- A custom policy implemented and compiled. See
  [Implement an Omni Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.13/policies-custom-implement-rust).

## Deploy a Custom Policy

1.  Create a configuration file called `custom-policy-example.yaml`.

2.  Save the file in the Omni Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

3.  Create the extension definition.

    Copy and paste the following YAML snippet into the new configuration file. The YAML defines the
    configuration and metadata properties for the custom policy:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ```

    - The `metadata.name` value contains the extension name.

    - The `Extension` inherits properties from other defined extensions. For example, `spec.extends`
      specifies that the extension is an `extension-definition`, and that it belongs in the
      `authentication` category (`extension-authentication`).

    - The `spec.properties` values define properties that configure the custom policy instance.

    - The `spec.required` value specifies the required properties.

4.  Encode the custom policy WASM binary implementation using `base64`.

    Encode the custom policy WASM binary implementation by executing the following command:

    ```ssh
    base64 <your-custom-policy-name>.wasm | tr -d '\n\r' > policy
    ```

    The command sends the encoded data to a file called `policy`. In the next step, substitute
    `<WASM_BINARY_IN_BASE64>` with this encoded data.

    > [!NOTE] If you compiled the policy using a target of `wasm32-unknown-unknown`, locate the
    > binary in `./target/wasm32-unknown-unknown/release`.
    >
    > If you compiled the policy using a target of `wasm32-wasi`, locate the binary in
    > `./target/wasm32-wasi/release`.

5.  Link the extension definition to the custom policy WASM binary implementation.

    In `custom-policy-example.yaml`, define another resource that contains the policy
    implementation:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ```

    - The `metadata.name` value contains the policy name, which must be different from the name
      specified in the definition.

    - The `spec.extends` value specifies the resource definition to inherit from. For example,
      `custom-local-example-definition` is the resource previously defined.

    - Substitute the `<WASM_BINARY_IN_BASE64>` value of `spec.properties.implementation.default`
      with the `base64` encoded WASM binary data, generated previously.

      > [!NOTE] You can include the policy definition and implementation in the same `Extension`
      > resource, but this generates a tighter coupling between them. It is therefore recommended to
      > separate the two into different resources.

6.  Link the custom policy to an API instance.

    In `custom-policy-example.yaml`, define another resource that links the policy to an API
    instance:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    - The `metadata.name` value contains the custom policy instance name.

    - The `spec.targetRef.name` value contains the name of the API instance on which to apply the
      custom policy. The API instance must already have been defined and applied.

    - The `spec.policyRef.name` value contains the custom policy implementation to apply.

    - The `spec.config` value contains policy configuration data.

7.  Apply the resources to the Omni Gateway instance.

    The complete `custom-policy-example.yaml` file now contains the following:

    ```yaml
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    Save the file in the Omni Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

A custom policy now applies to an API instance called `ingress-http`.

## See Also

- [Implement an Omni Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/1.13/policies-custom-implement-rust)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide)

<!-- document id=ca7879e252ad6dc2d72342d485b5bed3174c1ef1ecfef6fb9029d75405441516 url=/mulesoft/current/en-us/gateway/latest/local-deploy-custom-policy.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Deploying a Custom Policy for Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. The following steps demonstrate deploying and applying a custom filter (policy) to an API
running in Local Mode:

1.  Create a configuration YAML file.

2.  Save the file in the Omni Gateway configuration directory.

3.  Create the extension definition.

4.  Encode the custom policy WASM implementation using `base64`.

5.  Link the extension definition to the custom policy WASM binary implementation.

6.  Link the custom policy to an API instance.

7.  Apply the resources to the Omni Gateway instance.

## Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in Local Mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more
  information about installing and running the gateway.

- Your upstream service URL. See
  [Publishing a Simple API Instance in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-simple-api) for an example.

- A custom policy implemented and compiled. See
  [Implement an Omni Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/latest/policies-custom-implement-rust).

## Deploy a Custom Policy

1.  Create a configuration file called `custom-policy-example.yaml`.

2.  Save the file in the Omni Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

3.  Create the extension definition.

    Copy and paste the following YAML snippet into the new configuration file. The YAML defines the
    configuration and metadata properties for the custom policy:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ```

    - The `metadata.name` value contains the extension name.

    - The `Extension` inherits properties from other defined extensions. For example, `spec.extends`
      specifies that the extension is an `extension-definition`, and that it belongs in the
      `authentication` category (`extension-authentication`).

    - The `spec.properties` values define properties that configure the custom policy instance.

    - The `spec.required` value specifies the required properties.

4.  Encode the custom policy WASM binary implementation using `base64`.

    Encode the custom policy WASM binary implementation by executing the following command:

    ```ssh
    base64 <your-custom-policy-name>.wasm | tr -d '\n\r' > policy
    ```

    The command sends the encoded data to a file called `policy`. In the next step, substitute
    `<WASM_BINARY_IN_BASE64>` with this encoded data.

    > [!NOTE] If you compiled the policy using a target of `wasm32-unknown-unknown`, locate the
    > binary in `./target/wasm32-unknown-unknown/release`.
    >
    > If you compiled the policy using a target of `wasm32-wasi`, locate the binary in
    > `./target/wasm32-wasi/release`.

5.  Link the extension definition to the custom policy WASM binary implementation.

    In `custom-policy-example.yaml`, define another resource that contains the policy
    implementation:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ```

    - The `metadata.name` value contains the policy name, which must be different from the name
      specified in the definition.

    - The `spec.extends` value specifies the resource definition to inherit from. For example,
      `custom-local-example-definition` is the resource previously defined.

    - Substitute the `<WASM_BINARY_IN_BASE64>` value of `spec.properties.implementation.default`
      with the `base64` encoded WASM binary data, generated previously.

      > [!NOTE] You can include the policy definition and implementation in the same `Extension`
      > resource, but this generates a tighter coupling between them. It is therefore recommended to
      > separate the two into different resources.

6.  Link the custom policy to an API instance.

    In `custom-policy-example.yaml`, define another resource that links the policy to an API
    instance:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    - The `metadata.name` value contains the custom policy instance name.

    - The `spec.targetRef.name` value contains the name of the API instance on which to apply the
      custom policy. The API instance must already have been defined and applied.

    - The `spec.policyRef.name` value contains the custom policy implementation to apply.

    - The `spec.config` value contains policy configuration data.

7.  Apply the resources to the Omni Gateway instance.

    The complete `custom-policy-example.yaml` file now contains the following:

    ```yaml
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-definition
    spec:
      extends:
        - name: extension-authentication
        - name: extension-definition
      properties:
        secret-value:
          type: string
      required:
        - secret-value
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: Extension
    metadata:
      name: custom-local-example-flex
    spec:
      extends:
        - name: custom-local-example-definition
        - name: envoy-filter
        - name: proxy-wasm-filter
      properties:
        rootId:
          type: string
          default: main
        implementation:
          type: string
          default: base64://<WASM_BINARY_IN_BASE64>
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: PolicyBinding
    metadata:
      name: custom-local-example
    spec:
      targetRef:
        kind: ApiInstance
        name: ingress-http
      policyRef:
        kind: Extension
        name: custom-local-example-flex
      config:
        secret-value: "an-example-value"
    ```

    Save the file in the Omni Gateway configuration directory. For example:

    - `/etc/mulesoft/flex-gateway/conf.d/policies`

A custom policy now applies to an API instance called `ingress-http`.

## See Also

- [Implement an Omni Gateway Custom Policy in Rust](https://docs.mulesoft.com/gateway/latest/policies-custom-implement-rust)

- [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide)

<!-- document id=caf5aec522b150da4885315a306c6bbf15231e30c0fc52401d01fbe35fb899eb url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-managed-ingress-egress.md -->

---
product: Omni Gateway
version: 1.12
---

# Deploying Agent Network Ingress and Egress Managed Flex Gateways

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Agent Network deployments require both an ingress and egress Flex Gateway. The ingress Flex Gateway
sits in front of broker and API endpoints to manage and enforce policies on traffic entering the
network. The egress Flex Gateway sits on outbound paths from brokers and agents to external agents
and enforces policies, manages connections, and emits telemetry data.

The only functional difference between ingress and egress Flex Gateways, is that the egress Gateway
doesn’t have a public endpoint. Only clients inside the same private space as the egress gateway can
make requests to it. Traffic leaving the private space to external services passes through the
egress gateway.

![Agent Network showing agents and MCP servers defined in YAML and published to Exchange, with traffic through Flex Gateway, governed by API Manager, and observed in Monitoring and Visualizer](/mulesoft/current/en-us/gateway/1.12/_images/agent-fabric-architecture.png)

> [!NOTE] For a more detailed description of this architecture diagram, see
> [Agent Network Architecture](https://docs.mulesoft.com/agent-network/latest/af-agent-networks#agent-network-architecture).

## Deploy Ingress and Egress Managed Flex Gateways

The easiest way to deploy your Agent Network ingress and egress Flex Gateways is by using Anypoint
Code Builder or Anypoint Command Line Interface (CLI):

- [Set Up Agent Network Gateways by Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/latest/af-get-started#setup-gateways)

- [Set Up Agent Network Gateways by Using Anypoint CLI](https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-setup-gateways)

To manually deploy both ingress and egress managed Flex Gateways using the Runtime Manager UI, see
[Deploy a Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-managed-set-up).

For ingress gateways, configure a **Public endpoint** in the advanced options **Ingress** tab. For
egress gateways, verify that there’s no **Public endpoint** configured. To prevent confusion, give a
descriptive name defining the gateway as either ingress or egress.

## Apply Inbound and Outbound Policies

Inbound policies are policies that are enforced on all traffic accessing an instance’s endpoint.
Outbound policies are policies that are enforced on all traffic accessing a specific URL and are
only applied to that URL. For example, for an agent instance that has multiple upstreams, an inbound
client ID enforcement policy enforces client ID verification for all traffic accessing the agent
instance. However, an outbound policy might be applied to only one of the instance’s upstream.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

<!-- document id=f260da9782cd02178b30292da9f06e248835074a7132482a5db5a710389cc28d url=/mulesoft/current/en-us/gateway/1.13/gateway-managed-ingress-egress.md -->

---
product: Omni Gateway
version: 1.13
---

# Deploying Agent Network Ingress and Egress Managed Omni Gateways

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Agent Network deployments require both an ingress and egress Omni Gateway. The ingress Omni Gateway
sits in front of broker and API endpoints to manage and enforce policies on traffic entering the
network. The egress Omni Gateway sits on outbound paths from brokers and agents to external agents
and enforces policies, manages connections, and emits telemetry data.

The only functional difference between ingress and egress Omni Gateways, is that the egress Gateway
doesn’t have a public endpoint. Only clients inside the same private space as the egress gateway can
make requests to it. Traffic leaving the private space to external services passes through the
egress gateway.

![Agent Network showing agents and MCP servers defined in YAML and published to Exchange, with traffic through Omni Gateway, governed by API Manager, and observed in Monitoring and Visualizer](/mulesoft/current/en-us/gateway/1.13/_images/agent-fabric-architecture.png)

> [!NOTE] For a more detailed description of this architecture diagram, see
> [Agent Network Architecture](https://docs.mulesoft.com/agent-network/latest/af-agent-networks#agent-network-architecture).

## Deploy Ingress and Egress Managed Omni Gateways

The easiest way to deploy your Agent Network ingress and egress Omni Gateways is by using Anypoint
Code Builder or Anypoint Command Line Interface (CLI):

- [Set Up Agent Network Gateways by Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/latest/af-get-started#setup-gateways)

- [Set Up Agent Network Gateways by Using Anypoint CLI](https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-setup-gateways)

To manually deploy both ingress and egress managed Omni Gateways using the Runtime Manager UI, see
[Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-managed-set-up).

For ingress gateways, configure a **Public endpoint** in the advanced options **Ingress** tab. For
egress gateways, verify that there’s no **Public endpoint** configured. To prevent confusion, give a
descriptive name defining the gateway as either ingress or egress.

## Apply Inbound and Outbound Policies

Inbound policies are policies that are enforced on all traffic accessing an instance’s endpoint.
Outbound policies are policies that are enforced on all traffic accessing a specific URL and are
only applied to that URL. For example, for an agent instance that has multiple upstreams, an inbound
client ID enforcement policy enforces client ID verification for all traffic accessing the agent
instance. However, an outbound policy might be applied to only one of the instance’s upstream.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

<!-- document id=b8fb7ca58ed7f7eedec639dd3b16a95cc8709c2c5c41485aa869219df33beb4d url=/mulesoft/current/en-us/gateway/latest/gateway-managed-ingress-egress.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Deploying Agent Network Ingress and Egress Managed Omni Gateways

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Agent Network deployments require both an ingress and egress Omni Gateway. The ingress Omni Gateway
sits in front of broker and API endpoints to manage and enforce policies on traffic entering the
network. The egress Omni Gateway sits on outbound paths from brokers and agents to external agents
and enforces policies, manages connections, and emits telemetry data.

The only functional difference between ingress and egress Omni Gateways, is that the egress Gateway
doesn’t have a public endpoint. Only clients inside the same private space as the egress gateway can
make requests to it. Traffic leaving the private space to external services passes through the
egress gateway.

![Agent Network showing agents and MCP servers defined in YAML and published to Exchange, with traffic through Omni Gateway, governed by API Manager, and observed in Monitoring and Visualizer](/mulesoft/current/en-us/gateway/latest/_images/agent-fabric-architecture.png)

> [!NOTE] For a more detailed description of this architecture diagram, see
> [Agent Network Architecture](https://docs.mulesoft.com/agent-network/latest/af-agent-networks#agent-network-architecture).

## Deploy Ingress and Egress Managed Omni Gateways

The easiest way to deploy your Agent Network ingress and egress Omni Gateways is by using Anypoint
Code Builder or Anypoint Command Line Interface (CLI):

- [Set Up Agent Network Gateways by Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/latest/af-get-started#setup-gateways)

- [Set Up Agent Network Gateways by Using Anypoint CLI](https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-setup-gateways)

To manually deploy both ingress and egress managed Omni Gateways using the Runtime Manager UI, see
[Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up).

For ingress gateways, configure a **Public endpoint** in the advanced options **Ingress** tab. For
egress gateways, verify that there’s no **Public endpoint** configured. To prevent confusion, give a
descriptive name defining the gateway as either ingress or egress.

## Apply Inbound and Outbound Policies

Inbound policies are policies that are enforced on all traffic accessing an instance’s endpoint.
Outbound policies are policies that are enforced on all traffic accessing a specific URL and are
only applied to that URL. For example, for an agent instance that has multiple upstreams, an inbound
client ID enforcement policy enforces client ID verification for all traffic accessing the agent
instance. However, an outbound policy might be applied to only one of the instance’s upstream.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

<!-- document id=2a0e12b0166af3a52aaea273158cd835fb2711aa4be8e54e1b6543b129452546 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-disable-logs.md -->

---
product: Omni Gateway
version: 1.12
---

# Disabling Flex Gateway Log Output to Anypoint Platform

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway logging provides insights into startup, shutdown, API requests, API responses,
policies, and Fluent Bit. Logging enables developers and administrators to identify and address
issues or anomalies. However, disabling log output to Anypoint Platform might be necessary.

Before disabling log output, consider the potential impact on troubleshooting capabilities. In some
cases, it’s more appropriate to adjust the log verbosity level.

You can disable sending the following logs to Anypoint Platform:

- Runtime logs, including:

  - The startup and shutdown of Flex Gateway, Fluent Bit, and Envoy.

  - Deployed APIs and policies.

  - Possible misconfigurations of Flex Gateway or other errors.

- Access logs, including:

  - The description of incoming interaction with Envoy over a period of time.

  - Incoming requests and responses for specific APIs.

> [!NOTE] You can only disable logs sent to Anypoint Platform. Standard output (STDOUT) remains
> unchanged.

You disable sending logs to Anypoint Platform by using a local configuration file. The following
tutorial describes how to create and deploy the file.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#containers"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Disable Anypoint Platform Log Output for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#containers">Disable Anypoint Platform Log Output for Flex Gateway in a Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Disable Anypoint Platform Log Output for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td><td><div><div><p><a href="#openshift">Disable Anypoint Platform Log Output for Flex Gateway in an OpenShift Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Flex Gateway log output, complete the following task:

- Depending on your output, ensure that the service where you direct logs to is operational. For
  more information about log output services, refer to
  [Configuring Flex Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.12/flex-conn-third-party-logs-config).

## Disable Anypoint Platform Log Output for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in your Flex Gateway configuration directory. For example:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/disable-logs-config.yaml
    ```

2.  In the configuration file, configure either or both `spec.logging.runtimeLogs.outputs.anypoint`
    and `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

3.  Save the file.

## Disable Anypoint Platform Log Output for Flex Gateway in a Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to step 4.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Navigate to the `app` directory.

4.  Create a new configuration YAML file named `disable-logs-config.yaml`.

5.  In the configuration file, configure either or both `spec.logging.runtimeLogs.outputs.anypoint`
    and `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

6.  Save the configuration file.

7.  Restart your Flex Gateway with the configuration directory volume:

    - Docker

    - Podman

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

    ```ssh
    podman run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    docker.io/mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

## Disable Anypoint Platform Log Output for Flex Gateway in a Kubernetes Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Configure either or both `spec.logging.runtimeLogs.outputs.anypoint` and
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## Disable Anypoint Platform Log Output for Flex Gateway in an OpenShift Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Configure either or both `spec.logging.runtimeLogs.outputs.anypoint` and
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## See Also

- [Configuring Flex Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.12/flex-conn-third-party-logs-config)

- [Message Logging Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-message-logging)

- [Registering and Running Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

<!-- document id=96b788c1acde045bcdd450875575b73665381ddf344d0c44499e0b30c9ad7f62 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-disable-logs.md -->

---
product: Omni Gateway
version: 1.9
---

# Disabling Flex Gateway Log Output to Anypoint Platform

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway logging provides insights into startup, shutdown, API requests, API responses,
policies, and Fluent Bit. Logging enables developers and administrators to identify and address
issues or anomalies. However, disabling log output to Anypoint Platform might be necessary.

Before disabling log output, consider the potential impact on troubleshooting capabilities. In some
cases, it’s more appropriate to adjust the log verbosity level.

You can disable sending the following logs to Anypoint Platform:

- Runtime logs, including:

  - The startup and shutdown of Flex Gateway, Fluent Bit, and Envoy.

  - Deployed APIs and policies.

  - Possible misconfigurations of Flex Gateway or other errors.

- Access logs, including:

  - The description of incoming interaction with Envoy over a period of time.

  - Incoming requests and responses for specific APIs.

> [!NOTE] You can only disable logs sent to Anypoint Platform. Standard output (STDOUT) remains
> unchanged.

You disable sending logs to Anypoint Platform by using a local configuration file. The following
tutorial describes how to create and deploy the file.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#containers"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Disable Anypoint Platform Log Output for Flex Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#containers">Disable Anypoint Platform Log Output for Flex Gateway in a Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Disable Anypoint Platform Log Output for Flex Gateway in a Kubernetes Cluster</a></p></div></div></td><td><div><div><p><a href="#openshift">Disable Anypoint Platform Log Output for Flex Gateway in an OpenShift Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Flex Gateway log output, complete the following task:

- Depending on your output, ensure that the service where you direct logs to is operational. For
  more information about log output services, refer to
  [Configuring Flex Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.9/flex-conn-third-party-logs-config).

## Disable Anypoint Platform Log Output for Flex Gateway as a Linux Service

1.  Create a YAML configuration file in your Flex Gateway configuration directory. For example:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/disable-logs-config.yaml
    ```

2.  In the configuration file, set either `spec.logging.runtimeLogs.outputs.anypoint` or
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

3.  Save the file.

## Disable Anypoint Platform Log Output for Flex Gateway in a Container

> [!NOTE] If you have already added a volume for a folder with your Flex Gateway configuration
> files, skip to step 4.

1.  Press Ctrl+C to stop your Flex Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Flex Gateway configuration files.

3.  Navigate to the `app` directory.

4.  Create a new configuration YAML file named `disable-logs-config.yaml`.

5.  In the configuration file, set either `spec.logging.runtimeLogs.outputs.anypoint` or
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

6.  Save the configuration file.

7.  Restart your Flex Gateway with the configuration directory volume:

    - Docker

    - Podman

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

    ```ssh
    podman run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    docker.io/mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

## Disable Anypoint Platform Log Output for Flex Gateway in a Kubernetes Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Set either `spec.logging.runtimeLogs.outputs.anypoint` or
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## Disable Anypoint Platform Log Output for Flex Gateway in an OpenShift Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Set either `spec.logging.runtimeLogs.outputs.anypoint` or
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## See Also

- [Configuring Flex Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.9/flex-conn-third-party-logs-config)

- [Message Logging Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-message-logging)

- [Registering and Running Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

<!-- document id=57c30aadc1bc44ae4ac8ba6974e95e96153d9cde7aa652cdee0e4457e998de97 url=/mulesoft/current/en-us/gateway/1.13/conn-disable-logs.md -->

---
product: Omni Gateway
version: 1.13
---

# Disabling Omni Gateway Log Output to Anypoint Platform

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway logging provides insights into startup, shutdown, API requests, API responses,
policies, and Fluent Bit. Logging enables developers and administrators to identify and address
issues or anomalies. However, disabling log output to Anypoint Platform might be necessary.

Before disabling log output, consider the potential impact on troubleshooting capabilities. In some
cases, it’s more appropriate to adjust the log verbosity level.

You can disable sending the following logs to Anypoint Platform:

- Runtime logs, including:

  - The startup and shutdown of Omni Gateway, Fluent Bit, and Envoy.

  - Deployed APIs and policies.

  - Possible misconfigurations of Omni Gateway or other errors.

- Access logs, including:

  - The description of incoming interaction with Envoy over a period of time.

  - Incoming requests and responses for specific APIs.

> [!NOTE] You can only disable logs sent to Anypoint Platform. Standard output (STDOUT) remains
> unchanged.

You disable sending logs to Anypoint Platform by using a local configuration file. The following
tutorial describes how to create and deploy the file.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#containers"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Disable Anypoint Platform Log Output for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#containers">Disable Anypoint Platform Log Output for Omni Gateway in a Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Disable Anypoint Platform Log Output for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td><td><div><div><p><a href="#openshift">Disable Anypoint Platform Log Output for Omni Gateway in an OpenShift Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Omni Gateway log output, complete the following task:

- Depending on your output, ensure that the service where you direct logs to is operational. For
  more information about log output services, refer to
  [Configuring Omni Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.13/conn-third-party-logs-config).

## Disable Anypoint Platform Log Output for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in your Omni Gateway configuration directory. For example:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/disable-logs-config.yaml
    ```

2.  In the configuration file, configure either or both `spec.logging.runtimeLogs.outputs.anypoint`
    and `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

3.  Save the file.

## Disable Anypoint Platform Log Output for Omni Gateway in a Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to step 4.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Navigate to the `app` directory.

4.  Create a new configuration YAML file named `disable-logs-config.yaml`.

5.  In the configuration file, configure either or both `spec.logging.runtimeLogs.outputs.anypoint`
    and `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

6.  Save the configuration file.

7.  Restart your Omni Gateway with the configuration directory volume:

    - Docker

    - Podman

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

    ```ssh
    podman run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    docker.io/mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

## Disable Anypoint Platform Log Output for Omni Gateway in a Kubernetes Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Configure either or both `spec.logging.runtimeLogs.outputs.anypoint` and
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## Disable Anypoint Platform Log Output for Omni Gateway in an OpenShift Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Configure either or both `spec.logging.runtimeLogs.outputs.anypoint` and
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## See Also

- [Configuring Omni Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.13/conn-third-party-logs-config)

- [Message Logging Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-message-logging)

- [Registering and Running Omni Gateway](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

<!-- document id=fa2710e37e240fe6e0ac3dd773dce6162081c7bf8da097ed97ef171017cd4224 url=/mulesoft/current/en-us/gateway/latest/conn-disable-logs.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Disabling Omni Gateway Log Output to Anypoint Platform

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway logging provides insights into startup, shutdown, API requests, API responses,
policies, and Fluent Bit. Logging enables developers and administrators to identify and address
issues or anomalies. However, disabling log output to Anypoint Platform might be necessary.

Before disabling log output, consider the potential impact on troubleshooting capabilities. In some
cases, it’s more appropriate to adjust the log verbosity level.

You can disable sending the following logs to Anypoint Platform:

- Runtime logs, including:

  - The startup and shutdown of Omni Gateway, Fluent Bit, and Envoy.

  - Deployed APIs and policies.

  - Possible misconfigurations of Omni Gateway or other errors.

- Access logs, including:

  - The description of incoming interaction with Envoy over a period of time.

  - Incoming requests and responses for specific APIs.

> [!NOTE] You can only disable logs sent to Anypoint Platform. Standard output (STDOUT) remains
> unchanged.

You disable sending logs to Anypoint Platform by using a local configuration file. The following
tutorial describes how to create and deploy the file.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#containers"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Disable Anypoint Platform Log Output for Omni Gateway as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#containers">Disable Anypoint Platform Log Output for Omni Gateway in a Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Disable Anypoint Platform Log Output for Omni Gateway in a Kubernetes Cluster</a></p></div></div></td><td><div><div><p><a href="#openshift">Disable Anypoint Platform Log Output for Omni Gateway in an OpenShift Cluster</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before configuring Omni Gateway log output, complete the following task:

- Depending on your output, ensure that the service where you direct logs to is operational. For
  more information about log output services, refer to
  [Configuring Omni Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/latest/conn-third-party-logs-config).

## Disable Anypoint Platform Log Output for Omni Gateway as a Linux Service

1.  Create a YAML configuration file in your Omni Gateway configuration directory. For example:

    ```ssh
    sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/disable-logs-config.yaml
    ```

2.  In the configuration file, configure either or both `spec.logging.runtimeLogs.outputs.anypoint`
    and `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

3.  Save the file.

## Disable Anypoint Platform Log Output for Omni Gateway in a Container

> [!NOTE] If you have already added a volume for a folder with your Omni Gateway configuration
> files, skip to step 4.

1.  Press Ctrl+C to stop your Omni Gateway and any replicas.

2.  Create a folder named `app` in the directory with your Omni Gateway configuration files.

3.  Navigate to the `app` directory.

4.  Create a new configuration YAML file named `disable-logs-config.yaml`.

5.  In the configuration file, configure either or both `spec.logging.runtimeLogs.outputs.anypoint`
    and `spec.logging.accessLogs.outputs.anypoint` to `disabled`. The file resembles the following:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

6.  Save the configuration file.

7.  Restart your Omni Gateway with the configuration directory volume:

    - Docker

    - Podman

    ```ssh
    docker run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

    ```ssh
    podman run --rm \
    -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
    -p 8080:8080 \
    docker.io/mulesoft/flex-gateway
    ```

    > [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
    > following: `-e FLEX_NAME=<name-for-flex-replica> \`.

## Disable Anypoint Platform Log Output for Omni Gateway in a Kubernetes Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Configure either or both `spec.logging.runtimeLogs.outputs.anypoint` and
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## Disable Anypoint Platform Log Output for Omni Gateway in an OpenShift Cluster

To disable logging to Anypoint Platform:

1.  Create a new resource using a YAML configuration file with the following example output
    configuration details:

    ```yaml
    apiVersion: gateway.mulesoft.com/v1beta1
    kind: Configuration
    metadata:
      name: logging-config
    spec:
      logging:
        runtimeLogs:
          logLevel: info
          outputs:
            anypoint: disabled
        accessLogs:
          outputs:
            anypoint: disabled
    ```

2.  Configure either or both `spec.logging.runtimeLogs.outputs.anypoint` and
    `spec.logging.accessLogs.outputs.anypoint` to `disabled`.

## See Also

- [Configuring Omni Gateway Output for Third-Party Services](https://docs.mulesoft.com/gateway/latest/conn-third-party-logs-config)

- [Message Logging Policy](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging)

- [Registering and Running Omni Gateway](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

<!-- document id=33b9ffeff69d074b8a7e1773a23ac80927d4ce638720075bc35f388a4121c49b url=/mulesoft/current/en-us/gateway/1.12/flex-install.md -->

---
product: Omni Gateway
version: 1.12
---

# Downloading Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Download and install Flex Gateway as a Linux service, or download the Flex Gateway image from the
container registry. Downloading is a prerequisite to registering and running a gateway as a Linux
service or in a container, Kubernetes cluster, or OpenShift cluster.

To run Flex Gateway inside a virtual machine (VM), download and install it as a Linux service. To
run Flex Gateway in a container, Kubernetes cluster, or OpenShift cluster, download the Flex Gateway
image.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

See [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites) for details about hardware
and software requirements.

## Download and Install as a Linux Service

You can download and install Flex Gateway as a service in one of the following Linux environments:

#### ![2%](/mulesoft/current/en-us/gateway/1.12/_images/install-ubuntu-logo.png) Ubuntu

Download and install Flex Gateway as an Ubuntu service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions of Ubuntu:

- Ubuntu Jammy

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Flex Gateway as a Ubuntu service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Flex Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/ubuntu/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.12/_images/install-debian-logo.png) Debian

Download and install Flex Gateway as a Debian service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions of Debian:

- Debian Bookworm

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Flex Gateway as a Debian service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Flex Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.12/_images/install-amazon-linux-logo.png) Amazon Linux

Download and install Flex Gateway as an Amazon Linux service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) version of Amazon Linux:

- Amazon Linux 2023

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as an Amazon Linux service, run the command block that performs
the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/amazonlinux/2023/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/amazonlinux/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.12/_images/install-rhel-logo.png) Red Hat Enterprise Linux

Download and install Flex Gateway as a Red Hat Enterprise Linux service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions of RHEL:

- Red Hat Enterprise Linux (9)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

#### ![6%](/mulesoft/current/en-us/gateway/1.12/_images/install-rhel-ibm-logo.png) Red Hat Enterprise Linux on IBM Power

Download and install Flex Gateway as a Red Hat Enterprise Linux service on IBM Power

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions:

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.12/_images/install-centos-logo.png) CentOS

Download and install Flex Gateway as a CentOS service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) version of CentOS:

- CentOS 8

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as an CentOS service, run the command block that performs the
following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/centos/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/centos/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

Due to issues with the CentOS package manager you might encounter the following error:

Error: Failed to download metadata for repo 'AppStream': Cannot prepare internal mirrorlist: No URLs
in mirrorlist

If you encounter this error, run the following command:

```ssh
sudo sed -i -e "s|mirrorlist=|#mirrorlist=|g" -e "s|#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|g" /etc/yum.repos.d/CentOS-*
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

## Download Flex Gateway for Use in a Container

You can download and install Flex Gateway in one of the following containers:

#### ![2%](/mulesoft/current/en-us/gateway/1.12/_images/install-docker-logo.png) Docker

Download Flex Gateway for Use in a Docker Container

Download the Flex Gateway container image to prepare for registering and running a gateway in a
Docker container:

1.  Download the Flex Gateway Docker image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Flex Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

For more detail, see [Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.12/_images/install-podman-logo.png) Podman

Download Flex Gateway for Use in a Podman Container

Download the Flex Gateway container image to prepare for registering and running a gateway in a
Podman container:

1.  Download the Flex Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Flex Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

For more detail, see [Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.12/#connected-mode-vs-local-mode).

## Download Flex Gateway for Use in a Kubernetes Cluster

Download the Flex Gateway container image to prepare for registering and running a gateway in a
Kubernetes cluster. You can use the following container runtimes:

**Docker**

1.  Download the Flex Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Flex Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

**Podman**

1.  Download the Flex Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Flex Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

## Download Flex Gateway for Use in an OpenShift Cluster

Download the Flex Gateway container image to prepare for registering and running a gateway in an
OpenShift cluster. You can use the following container runtimes:

**Docker**

1.  Download the Flex Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Flex Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

**Podman**

1.  Download the Flex Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Flex Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

<!-- document id=3ba46f31b4a8c175f3a076b3e528a49c15fd2d21ba58d1dab4bcbd6e46a1cabf url=/mulesoft/current/en-us/gateway/1.9/flex-install.md -->

---
product: Omni Gateway
version: 1.9
---

# Downloading Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Download and install Flex Gateway as a Linux service, or download the Flex Gateway image from the
container registry. Downloading is a prerequisite to registering and running a gateway as a Linux
service or in a container, Kubernetes cluster, or OpenShift cluster.

To run Flex Gateway inside a virtual machine (VM), download and install it as a Linux service. To
run Flex Gateway in a container, Kubernetes cluster, or OpenShift cluster, download the Flex Gateway
image.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

See [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites) for details about hardware
and software requirements.

## Download and Install as a Linux Service

You can download and install Flex Gateway as a service in one of the following Linux environments:

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-ubuntu-logo.png) Ubuntu

Download and install Flex Gateway as an Ubuntu service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions of Ubuntu:

- Ubuntu (Focal, Jammy)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Flex Gateway as a Ubuntu service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Flex Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/ubuntu/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-debian-logo.png) Debian

Download and install Flex Gateway as a Debian service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions of Debian:

- Debian (Bullseye, Bookworm)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Flex Gateway as a Debian service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Flex Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-amazon-linux-logo.png) Amazon Linux

Download and install Flex Gateway as an Amazon Linux service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) version of Amazon Linux:

- Amazon Linux 2023

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as an Amazon Linux service, run the command block that performs
the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/amazonlinux/2023/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/amazonlinux/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-rhel-logo.png) Red Hat Enterprise Linux

Download and install Flex Gateway as a Red Hat Enterprise Linux service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions of RHEL:

- Red Hat Enterprise Linux (9)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![6%](/mulesoft/current/en-us/gateway/1.9/_images/install-rhel-ibm-logo.png) Red Hat Enterprise Linux on IBM Power

Download and install Flex Gateway as a Red Hat Enterprise Linux service on IBM Power

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions:

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-suse-logo.png) SUSE Linux Enterprise

Download and install Flex Gateway as a SUSE Linux Enterprise service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions:

- SUSE Linux Enterprise (SLES 15 SP3)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as a SUSE Linux Enterprise service, run the command block that
performs the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo rpm --import https://flex-packages.anypoint.mulesoft.com/suse/pubkey.gpg
sudo tee /etc/zypp/repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/suse/$releasever_major/main
gpgcheck = 1
gpgkey = https://flex-packages.anypoint.mulesoft.com/suse/pubkey.gpg
repo_gpgcheck = 1
enabled = 1
EOF

sudo zypper refresh -f flex-gateway
sudo zypper install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![6%](/mulesoft/current/en-us/gateway/1.9/_images/install-suse-ibm-logo.png) SUSE Linux Enterprise on IBM Power

Download and install Flex Gateway as a SUSE Linux Enterprise service on IBM Power

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) versions:

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as a SUSE Linux Enterprise service on IBM Power, run the
command block that performs the following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo rpm --import https://flex-packages.anypoint.mulesoft.com/suse/pubkey.gpg
sudo tee /etc/zypp/repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/suse/$releasever_major/main
gpgcheck = 1
gpgkey = https://flex-packages.anypoint.mulesoft.com/suse/pubkey.gpg
repo_gpgcheck = 1
enabled = 1
EOF

sudo zypper refresh -f flex-gateway
sudo zypper install -y flex-gateway
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-centos-logo.png) CentOS

Download and install Flex Gateway as a CentOS service

##### Software Requirements

Flex Gateway runs on the following Long Term Support (LTS) version of CentOS:

- CentOS 8

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Flex Gateway as an CentOS service, run the command block that performs the
following actions:

- Adds the Flex Gateway package repository with a reference to its public key

- Installs the Flex Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/centos/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/centos/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

Due to issues with the CentOS package manager you might encounter the following error:

Error: Failed to download metadata for repo 'AppStream': Cannot prepare internal mirrorlist: No URLs
in mirrorlist

If you encounter this error, run the following command:

```ssh
sudo sed -i -e "s|mirrorlist=|#mirrorlist=|g" -e "s|#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|g" /etc/yum.repos.d/CentOS-*
```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

## Download Flex Gateway for Use in a Container

You can download and install Flex Gateway in one of the following containers:

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-docker-logo.png) Docker

Download Flex Gateway for Use in a Docker Container

Download the Flex Gateway container image to prepare for registering and running a gateway in a
Docker container:

1.  Download the Flex Gateway Docker image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.9/_images/install-podman-logo.png) Podman

Download Flex Gateway for Use in a Podman Container

Download the Flex Gateway container image to prepare for registering and running a gateway in a
Podman container:

1.  Download the Flex Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

After downloading and installing, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.9/#connected-mode-vs-local-mode).

## Download Flex Gateway for Use in a Kubernetes Cluster

Download the Flex Gateway container image to prepare for registering and running a gateway in a
Kubernetes cluster. You can use the following container runtimes:

**Docker**

1.  Download the Flex Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

**Podman**

1.  Download the Flex Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

## Download Flex Gateway for Use in an OpenShift Cluster

Download the Flex Gateway container image to prepare for registering and running a gateway in an
OpenShift cluster. You can use the following container runtimes:

**Docker**

1.  Download the Flex Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

**Podman**

1.  Download the Flex Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Flex Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

After downloading the image, register Flex Gateway in [Connected](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

<!-- document id=99b8f8019db5f865e984c6cc6bf2e42dbf2fc6ae29e93c60728bdf0ba00a4437 url=/mulesoft/current/en-us/gateway/1.13/install.md -->

---
product: Omni Gateway
version: 1.13
---

# Downloading Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Download and install Omni Gateway as a Linux service, or download the Omni Gateway image from the
container registry. Downloading is a prerequisite to registering and running a gateway as a Linux
service or in a container, Kubernetes cluster, or OpenShift cluster.

To run Omni Gateway inside a virtual machine (VM), download and install it as a Linux service. To
run Omni Gateway in a container, Kubernetes cluster, or OpenShift cluster, download the Omni Gateway
image.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

See [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites) for details about hardware and
software requirements.

## Download and Install as a Linux Service

You can download and install Omni Gateway as a service in one of the following Linux environments:

#### ![2%](/mulesoft/current/en-us/gateway/1.13/_images/install-ubuntu-logo.png) Ubuntu

Download and install Omni Gateway as an Ubuntu service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions of Ubuntu:

- Ubuntu Jammy

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Omni Gateway as a Ubuntu service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Omni Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/ubuntu/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.13/_images/install-debian-logo.png) Debian

Download and install Omni Gateway as a Debian service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions of Debian:

- Debian Bookworm

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Omni Gateway as a Debian service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Omni Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.13/_images/install-amazon-linux-logo.png) Amazon Linux

Download and install Omni Gateway as an Amazon Linux service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) version of Amazon Linux:

- Amazon Linux 2023

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as an Amazon Linux service, run the command block that performs
the following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/amazonlinux/2023/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/amazonlinux/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.13/_images/install-rhel-logo.png) Red Hat Enterprise Linux

Download and install Omni Gateway as a Red Hat Enterprise Linux service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions of RHEL:

- Red Hat Enterprise Linux (9)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

#### ![6%](/mulesoft/current/en-us/gateway/1.13/_images/install-rhel-ibm-logo.png) Red Hat Enterprise Linux on IBM Power

Download and install Omni Gateway as a Red Hat Enterprise Linux service on IBM Power

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions:

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.13/_images/install-centos-logo.png) CentOS

Download and install Omni Gateway as a CentOS service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) version of CentOS:

- CentOS 8

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as an CentOS service, run the command block that performs the
following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/centos/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/centos/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

Due to issues with the CentOS package manager you might encounter the following error:

Error: Failed to download metadata for repo 'AppStream': Cannot prepare internal mirrorlist: No URLs
in mirrorlist

If you encounter this error, run the following command:

```ssh
sudo sed -i -e "s|mirrorlist=|#mirrorlist=|g" -e "s|#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|g" /etc/yum.repos.d/CentOS-*
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

## Download Omni Gateway for Use in a Container

You can download and install Omni Gateway in one of the following containers:

#### ![2%](/mulesoft/current/en-us/gateway/1.13/_images/install-docker-logo.png) Docker

Download Omni Gateway for Use in a Docker Container

Download the Omni Gateway container image to prepare for registering and running a gateway in a
Docker container:

1.  Download the Omni Gateway Docker image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

For more detail, see [Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/1.13/_images/install-podman-logo.png) Podman

Download Omni Gateway for Use in a Podman Container

Download the Omni Gateway container image to prepare for registering and running a gateway in a
Podman container:

1.  Download the Omni Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

For more detail, see [Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/1.13/#connected-mode-vs-local-mode).

## Download Omni Gateway for Use in a Kubernetes Cluster

Download the Omni Gateway container image to prepare for registering and running a gateway in a
Kubernetes cluster. You can use the following container runtimes:

**Docker**

1.  Download the Omni Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

**Podman**

1.  Download the Omni Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

## Download Omni Gateway for Use in an OpenShift Cluster

Download the Omni Gateway container image to prepare for registering and running a gateway in an
OpenShift cluster. You can use the following container runtimes:

**Docker**

1.  Download the Omni Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

**Podman**

1.  Download the Omni Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/1.13/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

<!-- document id=a99dc44f0e6cfb1fe60e75c53522d3f536e5355010936c11168a5436645d6ee2 url=/mulesoft/current/en-us/gateway/latest/install.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Downloading Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Download and install Omni Gateway as a Linux service, or download the Omni Gateway image from the
container registry. Downloading is a prerequisite to registering and running a gateway as a Linux
service or in a container, Kubernetes cluster, or OpenShift cluster.

To run Omni Gateway inside a virtual machine (VM), download and install it as a Linux service. To
run Omni Gateway in a container, Kubernetes cluster, or OpenShift cluster, download the Omni Gateway
image.

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

See [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites) for details about hardware and
software requirements.

## Download and Install as a Linux Service

You can download and install Omni Gateway as a service in one of the following Linux environments:

#### ![2%](/mulesoft/current/en-us/gateway/latest/_images/install-ubuntu-logo.png) Ubuntu

Download and install Omni Gateway as an Ubuntu service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions of Ubuntu:

- Ubuntu Jammy

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Omni Gateway as a Ubuntu service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Omni Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/ubuntu/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/latest/_images/install-debian-logo.png) Debian

Download and install Omni Gateway as a Debian service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions of Debian:

- Debian Bookworm

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

- [lsb\_release](https://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-PDA/LSB-PDA/lsbrelease.html)

##### Run Installation Commands

To download and install Omni Gateway as a Debian service, run the command block that performs the
following actions:

- Retrieves the public package keys and adds the package repository

- Updates the package list

- Updates `apt-get`

- Installs the Omni Gateway package

```ssh
curl -XGET https://flex-packages.anypoint.mulesoft.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://flex-packages.anypoint.mulesoft.com/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mulesoft.list
sudo apt update
sudo apt install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/latest/_images/install-amazon-linux-logo.png) Amazon Linux

Download and install Omni Gateway as an Amazon Linux service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) version of Amazon Linux:

- Amazon Linux 2023

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as an Amazon Linux service, run the command block that performs
the following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/amazonlinux/2023/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/amazonlinux/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/latest/_images/install-rhel-logo.png) Red Hat Enterprise Linux

Download and install Omni Gateway as a Red Hat Enterprise Linux service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions of RHEL:

- Red Hat Enterprise Linux (9)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

#### ![6%](/mulesoft/current/en-us/gateway/latest/_images/install-rhel-ibm-logo.png) Red Hat Enterprise Linux on IBM Power

Download and install Omni Gateway as a Red Hat Enterprise Linux service on IBM Power

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) versions:

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as a Red Hat Enterprise Linux service, run the command block
that performs the following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/rhel/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/rhel/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/latest/_images/install-centos-logo.png) CentOS

Download and install Omni Gateway as a CentOS service

##### Software Requirements

Omni Gateway runs on the following Long Term Support (LTS) version of CentOS:

- CentOS 8

##### Before You Begin

Before getting started, ensure that you have installed the following:

- [gnupg2](https://gnupg.org/)

##### Run Installation Commands

To download and install Omni Gateway as an CentOS service, run the command block that performs the
following actions:

- Adds the Omni Gateway package repository with a reference to its public key

- Installs the Omni Gateway package

```ssh
sudo tee /etc/yum.repos.d/flex-gateway.repo <<\EOF
[flex-gateway]
name = Anypoint Flex Gateway
baseurl = https://flex-packages.anypoint.mulesoft.com/centos/$releasever/main
gpgcheck=1
gpgkey=https://flex-packages.anypoint.mulesoft.com/centos/pubkey.gpg
repo_gpgcheck=1
enabled=1
EOF

sudo yum install -y flex-gateway
```

Due to issues with the CentOS package manager you might encounter the following error:

Error: Failed to download metadata for repo 'AppStream': Cannot prepare internal mirrorlist: No URLs
in mirrorlist

If you encounter this error, run the following command:

```ssh
sudo sed -i -e "s|mirrorlist=|#mirrorlist=|g" -e "s|#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|g" /etc/yum.repos.d/CentOS-*
```

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run). For more detail, see
[Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

## Download Omni Gateway for Use in a Container

You can download and install Omni Gateway in one of the following containers:

#### ![2%](/mulesoft/current/en-us/gateway/latest/_images/install-docker-logo.png) Docker

Download Omni Gateway for Use in a Docker Container

Download the Omni Gateway container image to prepare for registering and running a gateway in a
Docker container:

1.  Download the Omni Gateway Docker image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

For more detail, see [Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

#### ![2%](/mulesoft/current/en-us/gateway/latest/_images/install-podman-logo.png) Podman

Download Omni Gateway for Use in a Podman Container

Download the Omni Gateway container image to prepare for registering and running a gateway in a
Podman container:

1.  Download the Omni Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

For more detail, see [Connected Mode vs. Local Mode](https://docs.mulesoft.com/gateway/latest/#connected-mode-vs-local-mode).

## Download Omni Gateway for Use in a Kubernetes Cluster

Download the Omni Gateway container image to prepare for registering and running a gateway in a
Kubernetes cluster. You can use the following container runtimes:

**Docker**

1.  Download the Omni Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

**Podman**

1.  Download the Omni Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

## Download Omni Gateway for Use in an OpenShift Cluster

Download the Omni Gateway container image to prepare for registering and running a gateway in an
OpenShift cluster. You can use the following container runtimes:

**Docker**

1.  Download the Omni Gateway container image:

    ```ssh
    docker pull mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    docker images mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

**Podman**

1.  Download the Omni Gateway container image:

    ```ssh
    podman pull docker.io/mulesoft/flex-gateway:latest
    ```

2.  Verify that the download succeeded:

    ```ssh
    podman images docker.io/mulesoft/flex-gateway
    ```

    When successful, the command lists the Omni Gateway container image, for example:

    ```text
    REPOSITORY                   TAG
    mulesoft/flex-gateway        latest
    ```

For deployments using Docker images, add the Omni Gateway Docker image to your Docker registry to
ensure the image is available in the event of a Dockerhub outage.

After downloading and installing, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

After downloading the image, register Omni Gateway in [Connected](https://docs.mulesoft.com/gateway/latest/conn-reg-run) or
[Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

<!-- document id=3566dab59a55fc5878aadbef91e346ce491c6fa00ecccb8c747678137684706e url=/mulesoft/current/en-us/gateway/1.12/policies-included-external-authorization.md -->

---
product: Omni Gateway
version: 1.12
keywords: external authorization, authorization, flex gateway, gateway, policy
---

# External Authorization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>External Authorization</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Authenticates requests with an external gRPC or HTTP authorization service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden, invalid client application credentials</p></td></tr></tbody></table>

## Summary

The External Authorization policy forwards incoming client HTTP requests to an external gRPC or HTTP
authorization service to determine if the client HTTP request is authorized to access the upstream
service. If the request is authorized, Flex Gateway allows the request to pass to the upstream
service. For unauthorized accesses, Flex Gateway returns a `403` forbidden request error.

To forward request headers, such as an authorization token header, from the client HTTP request to
the authorization service, configure the **Allowed Headers** parameter. Additionally, for HTTP
authorization servers, use the **Headers to add** parameter to inject new headers into the
authorization request.

> [!IMPORTANT] Flex Gateway sends headers to the authorization service encoded in bytes. To send
> headers encoded in utf8, set the environment variable `FLEX_HEADER_RAW_VALUE_ENABLE=false`.

The External Authorization policy can also modify the client HTTP request and response headers with
additional information returned from the authorization service. For example, if an authorized user
makes a request with an access token header that corresponds to a username, the authorization
service can return a `username` header for Flex Gateway to append to the client HTTP request.

For gRPC authorization servers, if the authorization service returns headers with the authorization
response, Flex Gateway either appends these headers to the client HTTP request or overwrites the
header if it is present in the client request.

For HTTP authorization servers, you can configure what headers to append, overwrite, or ignore.
Policies with an HTTP server configured can also modify the client response returned from the
upstream service.

The External Authorization policy is an extension of the External Authorization filter native to
Envoy. To learn more about the External Authorization filter, see
[External Authorization Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter).
Not all External Authorization filter parameters are available to the External Authorization policy.
To find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the incoming HTTP request, ensure that you order the policies
> depending on if these modification must be present before sending the request to the authorization
> service. For more information about ordering policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder).

## Configuring Policy Parameters

To configure your policy parameters, see the following parameter references for the mode your Flex
Gateway is running in:

- [Flex Gateway Local Mode](#local-mode)

- [Managed Flex Gateway and Flex Gateway Connected Mode](#connected-mode)

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: <string> // REQUIRED
    serverType: <string> // REQUIRED, default "grpc"
    serverApiVersion: <string> // REQUIRED, default `v3`
    serviceRequestHeadersToAdd: <object-array> // OPTIONAL
      - key: <string>
        value: <string>
    serviceResponseUpstreamHeaders: <string-array> // OPTIONAL
    serviceResponseUpstreamHeadersToAppend: <string-array> // OPTIONAL
    serviceResponseClientHeaders: <string-array> // OPTIONAL
    serviceResponseClientHeadersOnSuccess: <string-array> // OPTIONAL
    pathPrefix: <string> // OPTIONAL
    requestTimeout: <number> // REQUIRED, default `5000`
    includePeerCertificate: <boolean> // REQUIRED, default `false`
    allowedHeaders: <string-array> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI by using this format: <code>h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>grpc</code></p></div></div></td><td><div><div><p>Type of external server. Supported values are <code>grpc</code> and <code>http</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverApiVersion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>v3</code></p></div></div></td><td><div><div><p>Transport protocol API version. Supported values are <code>v3</code> and <code>v2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>includePeerCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>If <code>true</code>, includes peer certificates in the authorization server request. Supported values are <code>true</code> and <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Defines custom headers and their value to inject into the authorization service request. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.value</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Value of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Flex Gateway overwrites coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeadersToAppend</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Flex Gateway appends coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service. Flex Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeadersOnSuccess</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service if the request is successfully authorized. Flex Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>pathPrefix</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p><code>requestTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>5000</code></p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service.</p></div></div></td></tr><tr><td><div><div><p><code>allowedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the client HTTP request to propagate to authorization request. By default, requests sent to gRPC servers include all client headers. Requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

### Resource Configuration Example

In the following configuration, a gRPC authorization service receives a request that includes the
peer certificates and authorization token header:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: h2://ext-authz-grpc-service:9001
    serverType: "grpc"
    includePeerCertificate: "true"
    allowedHeaders:
      - access-token
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>External authorization service URI</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>External authorization server type</p></div></div></td><td><div><div><p>Type of external server.</p></div></div></td></tr><tr><td><div><div><p>Server API version</p></div></div></td><td><div><div><p>Transport protocol API version.</p></div></div></td></tr><tr><td><div><div><p>Include peer certificates in the authorization server request</p></div></div></td><td><div><div><p>Includes peer certificates in the authorization server request.</p></div></div></td></tr><tr><td><div><div><p>Path prefix</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p>Request timeout</p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service. By default, the request timeout is 5000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Allowed headers</p></div></div></td><td><div><div><p>By default, requests sent to gRPC servers include all client headers and requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow during the
External Authorization policy execution:

![A sequence diagram that illustrates the interaction between a user, an API gateway, a database, and an API](/mulesoft/current/en-us/gateway/1.12/_images/ext-auth-policy.png)

1.  The client makes an HTTP request to the API instance exposed by Flex Gateway.

2.  Flex Gateway forwards the request consisting of the client’s request and headers to the
    authorization service.

3.  The authorization services sends the authorization response back to Flex Gateway:

    - If the request isn’t authorized, Flex Gateway appends any necessary headers and returns a
      `403` forbidden access code to the client.

    - If the request is authorized, Flex Gateway appends the header data to the client request, if
      necessary, and allows the request to pass to the upstream service.

4.  Flex Gateway appends any necessary headers and returns the response as normal.

<!-- document id=cfe34ef76135124601b76e4bb9f0940a7e8e097000b4a12e93eb860eb265dd71 url=/mulesoft/current/en-us/gateway/1.13/policies-included-external-authorization.md -->

---
product: Omni Gateway
version: 1.13
keywords: external authorization, authorization, flex gateway, gateway, policy
---

# External Authorization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>External Authorization</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Authenticates requests with an external gRPC or HTTP authorization service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-authorization-release-notes">External Authorization Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden, invalid client application credentials</p></td></tr></tbody></table>

## Summary

The External Authorization policy forwards incoming client HTTP requests to an external gRPC or HTTP
authorization service to determine if the client HTTP request is authorized to access the upstream
service. If the request is authorized, Omni Gateway allows the request to pass to the upstream
service. For unauthorized accesses, Omni Gateway returns a `403` forbidden request error.

To forward request headers, such as an authorization token header, from the client HTTP request to
the authorization service, configure the **Allowed Headers** parameter. Additionally, for HTTP
authorization servers, use the **Headers to add** parameter to inject new headers into the
authorization request.

> [!IMPORTANT] Omni Gateway sends headers to the authorization service encoded in bytes. To send
> headers encoded in utf8, set the environment variable `FLEX_HEADER_RAW_VALUE_ENABLE=false`.

The External Authorization policy can also modify the client HTTP request and response headers with
additional information returned from the authorization service. For example, if an authorized user
makes a request with an access token header that corresponds to a username, the authorization
service can return a `username` header for Omni Gateway to append to the client HTTP request.

For gRPC authorization servers, if the authorization service returns headers with the authorization
response, Omni Gateway either appends these headers to the client HTTP request or overwrites the
header if it is present in the client request.

For HTTP authorization servers, you can configure what headers to append, overwrite, or ignore.
Policies with an HTTP server configured can also modify the client response returned from the
upstream service.

The External Authorization policy is an extension of the External Authorization filter native to
Envoy. To learn more about the External Authorization filter, see
[External Authorization Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter).
Not all External Authorization filter parameters are available to the External Authorization policy.
To find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the incoming HTTP request, ensure that you order the policies
> depending on if these modification must be present before sending the request to the authorization
> service. For more information about ordering policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder).

## Configuring Policy Parameters

To configure your policy parameters, see the following parameter references for the mode your Omni
Gateway is running in:

- [Omni Gateway Local Mode](#local-mode)

- [Managed Omni Gateway and Omni Gateway Connected Mode](#connected-mode)

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: <string> // REQUIRED
    serverType: <string> // REQUIRED, default "grpc"
    serverApiVersion: <string> // REQUIRED, default `v3`
    serviceRequestHeadersToAdd: <object-array> // OPTIONAL
      - key: <string>
        value: <string>
    serviceResponseUpstreamHeaders: <string-array> // OPTIONAL
    serviceResponseUpstreamHeadersToAppend: <string-array> // OPTIONAL
    serviceResponseClientHeaders: <string-array> // OPTIONAL
    serviceResponseClientHeadersOnSuccess: <string-array> // OPTIONAL
    pathPrefix: <string> // OPTIONAL
    requestTimeout: <number> // REQUIRED, default `5000`
    includePeerCertificate: <boolean> // REQUIRED, default `false`
    allowedHeaders: <string-array> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI by using this format: <code>h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>grpc</code></p></div></div></td><td><div><div><p>Type of external server. Supported values are <code>grpc</code> and <code>http</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverApiVersion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>v3</code></p></div></div></td><td><div><div><p>Transport protocol API version. Supported values are <code>v3</code> and <code>v2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>includePeerCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>If <code>true</code>, includes peer certificates in the authorization server request. Supported values are <code>true</code> and <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Defines custom headers and their value to inject into the authorization service request. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.value</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Value of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Omni Gateway overwrites coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeadersToAppend</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Omni Gateway appends coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service. Omni Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeadersOnSuccess</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service if the request is successfully authorized. Omni Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>pathPrefix</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p><code>requestTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>5000</code></p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service.</p></div></div></td></tr><tr><td><div><div><p><code>allowedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the client HTTP request to propagate to authorization request. By default, requests sent to gRPC servers include all client headers. Requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

### Resource Configuration Example

In the following configuration, a gRPC authorization service receives a request that includes the
peer certificates and authorization token header:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: h2://ext-authz-grpc-service:9001
    serverType: "grpc"
    includePeerCertificate: "true"
    allowedHeaders:
      - access-token
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>External authorization service URI</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>External authorization server type</p></div></div></td><td><div><div><p>Type of external server.</p></div></div></td></tr><tr><td><div><div><p>Server API version</p></div></div></td><td><div><div><p>Transport protocol API version.</p></div></div></td></tr><tr><td><div><div><p>Include peer certificates in the authorization server request</p></div></div></td><td><div><div><p>Includes peer certificates in the authorization server request.</p></div></div></td></tr><tr><td><div><div><p>Path prefix</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p>Request timeout</p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service. By default, the request timeout is 5000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Allowed headers</p></div></div></td><td><div><div><p>By default, requests sent to gRPC servers include all client headers and requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow during the
External Authorization policy execution:

![A sequence diagram that illustrates the interaction between a user, an API gateway, a database, and an API](/mulesoft/current/en-us/gateway/1.13/_images/ext-auth-policy.png)

1.  The client makes an HTTP request to the API instance exposed by Omni Gateway.

2.  Omni Gateway forwards the request consisting of the client’s request and headers to the
    authorization service.

3.  The authorization services sends the authorization response back to Omni Gateway:

    - If the request isn’t authorized, Omni Gateway appends any necessary headers and returns a
      `403` forbidden access code to the client.

    - If the request is authorized, Omni Gateway appends the header data to the client request, if
      necessary, and allows the request to pass to the upstream service.

4.  Omni Gateway appends any necessary headers and returns the response as normal.

<!-- document id=5375c71d9304332ad14445ec8e20e4593caa5ec87b4a3f4b98b8ccd4b235297f url=/mulesoft/current/en-us/gateway/1.9/policies-included-external-authorization.md -->

---
product: Omni Gateway
version: 1.9
keywords: external authorization, authorization, flex gateway, gateway, policy
---

# External Authorization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>External Authorization</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Authenticates requests with an external gRPC or HTTP authorization service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden, invalid client application credentials</p></td></tr></tbody></table>

## Summary

The External Authorization policy forwards incoming client HTTP requests to an external gRPC or HTTP
authorization service to determine if the client HTTP request is authorized to access the upstream
service. If the request is authorized, Flex Gateway allows the request to pass to the upstream
service. For unauthorized accesses, Flex Gateway returns a `403` forbidden request error.

To forward request headers, such as an authorization token header, from the client HTTP request to
the authorization service, configure the **Allowed Headers** parameter. Additionally, for HTTP
authorization servers, use the **Headers to add** parameter to inject new headers into the
authorization request.

> [!IMPORTANT] Flex Gateway sends headers to the authorization service encoded in bytes. To send
> headers encoded in utf8, set the environment variable `FLEX_HEADER_RAW_VALUE_ENABLE=false`.

The External Authorization policy can also modify the client HTTP request and response headers with
additional information returned from the authorization service. For example, if an authorized user
makes a request with an access token header that corresponds to a username, the authorization
service can return a `username` header for Flex Gateway to append to the client HTTP request.

For gRPC authorization servers, if the authorization service returns headers with the authorization
response, Flex Gateway either appends these headers to the client HTTP request or overwrites the
header if it is present in the client request.

For HTTP authorization servers, you can configure what headers to append, overwrite, or ignore.
Policies with an HTTP server configured can also modify the client response returned from the
upstream service.

The External Authorization policy is an extension of the External Authorization filter native to
Envoy. To learn more about the External Authorization filter, see
[External Authorization Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter).
Not all External Authorization filter parameters are available to the External Authorization policy.
To find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the incoming HTTP request, ensure that you order the policies
> depending on if these modification must be present before sending the request to the authorization
> service. For more information about ordering policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.9/policies-reorder).

## Configuring Policy Parameters

To configure your policy parameters, see the following parameter references for the mode your Flex
Gateway is running in:

- [Flex Gateway Local Mode](#local-mode)

- [Managed Flex Gateway and Flex Gateway Connected Mode](#connected-mode)

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: <string> // REQUIRED
    serverType: <string> // REQUIRED, default "grpc"
    serverApiVersion: <string> // REQUIRED, default `v3`
    serviceRequestHeadersToAdd: <object-array> // OPTIONAL
      - key: <string>
        value: <string>
    serviceResponseUpstreamHeaders: <string-array> // OPTIONAL
    serviceResponseUpstreamHeadersToAppend: <string-array> // OPTIONAL
    serviceResponseClientHeaders: <string-array> // OPTIONAL
    serviceResponseClientHeadersOnSuccess: <string-array> // OPTIONAL
    pathPrefix: <string> // OPTIONAL
    requestTimeout: <number> // REQUIRED, default `5000`
    includePeerCertificate: <boolean> // REQUIRED, default `false`
    allowedHeaders: <string-array> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI by using this format: <code>h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>grpc</code></p></div></div></td><td><div><div><p>Type of external server. Supported values are <code>grpc</code> and <code>http</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverApiVersion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>v3</code></p></div></div></td><td><div><div><p>Transport protocol API version. Supported values are <code>v3</code> and <code>v2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>includePeerCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>If <code>true</code>, includes peer certificates in the authorization server request. Supported values are <code>true</code> and <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Defines custom headers and their value to inject into the authorization service request. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.value</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Value of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Flex Gateway overwrites coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeadersToAppend</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Flex Gateway appends coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service. Flex Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeadersOnSuccess</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service if the request is successfully authorized. Flex Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>pathPrefix</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p><code>requestTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>5000</code></p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service.</p></div></div></td></tr><tr><td><div><div><p><code>allowedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the client HTTP request to propagate to authorization request. By default, requests sent to gRPC servers include all client headers. Requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

### Resource Configuration Example

In the following configuration, a gRPC authorization service receives a request that includes the
peer certificates and authorization token header:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: h2://ext-authz-grpc-service:9001
    serverType: "grpc"
    includePeerCertificate: "true"
    allowedHeaders:
      - access-token
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>External authorization service URI</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>External authorization server type</p></div></div></td><td><div><div><p>Type of external server.</p></div></div></td></tr><tr><td><div><div><p>Server API version</p></div></div></td><td><div><div><p>Transport protocol API version.</p></div></div></td></tr><tr><td><div><div><p>Include peer certificates in the authorization server request</p></div></div></td><td><div><div><p>Includes peer certificates in the authorization server request.</p></div></div></td></tr><tr><td><div><div><p>Path prefix</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p>Request timeout</p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service. By default, the request timeout is 5000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Allowed headers</p></div></div></td><td><div><div><p>By default, requests sent to gRPC servers include all client headers and requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow during the
External Authorization policy execution:

![A sequence diagram that illustrates the interaction between a user, an API gateway, a database, and an API](/mulesoft/current/en-us/gateway/1.9/_images/ext-auth-policy.png)

1.  The client makes an HTTP request to the API instance exposed by Flex Gateway.

2.  Flex Gateway forwards the request consisting of the client’s request and headers to the
    authorization service.

3.  The authorization services sends the authorization response back to Flex Gateway:

    - If the request isn’t authorized, Flex Gateway appends any necessary headers and returns a
      `403` forbidden access code to the client.

    - If the request is authorized, Flex Gateway appends the header data to the client request, if
      necessary, and allows the request to pass to the upstream service.

4.  Flex Gateway appends any necessary headers and returns the response as normal.

<!-- document id=ee067b203509d1aec8b0134e877a04bf0d40b7c4bfe05b4e6addd3459d95c214 url=/mulesoft/current/en-us/gateway/latest/policies-included-external-authorization.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: external authorization, authorization, flex gateway, gateway, policy
---

# External Authorization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>External Authorization</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Authenticates requests with an external gRPC or HTTP authorization service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-authorization-release-notes">External Authorization Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden, invalid client application credentials</p></td></tr></tbody></table>

## Summary

The External Authorization policy forwards incoming client HTTP requests to an external gRPC or HTTP
authorization service to determine if the client HTTP request is authorized to access the upstream
service. If the request is authorized, Omni Gateway allows the request to pass to the upstream
service. For unauthorized accesses, Omni Gateway returns a `403` forbidden request error.

To forward request headers, such as an authorization token header, from the client HTTP request to
the authorization service, configure the **Allowed Headers** parameter. Additionally, for HTTP
authorization servers, use the **Headers to add** parameter to inject new headers into the
authorization request.

> [!IMPORTANT] Omni Gateway sends headers to the authorization service encoded in bytes. To send
> headers encoded in utf8, set the environment variable `FLEX_HEADER_RAW_VALUE_ENABLE=false`.

The External Authorization policy can also modify the client HTTP request and response headers with
additional information returned from the authorization service. For example, if an authorized user
makes a request with an access token header that corresponds to a username, the authorization
service can return a `username` header for Omni Gateway to append to the client HTTP request.

For gRPC authorization servers, if the authorization service returns headers with the authorization
response, Omni Gateway either appends these headers to the client HTTP request or overwrites the
header if it is present in the client request.

For HTTP authorization servers, you can configure what headers to append, overwrite, or ignore.
Policies with an HTTP server configured can also modify the client response returned from the
upstream service.

The External Authorization policy is an extension of the External Authorization filter native to
Envoy. To learn more about the External Authorization filter, see
[External Authorization Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter).
Not all External Authorization filter parameters are available to the External Authorization policy.
To find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the incoming HTTP request, ensure that you order the policies
> depending on if these modification must be present before sending the request to the authorization
> service. For more information about ordering policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder).

## Configuring Policy Parameters

To configure your policy parameters, see the following parameter references for the mode your Omni
Gateway is running in:

- [Omni Gateway Local Mode](#local-mode)

- [Managed Omni Gateway and Omni Gateway Connected Mode](#connected-mode)

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: <string> // REQUIRED
    serverType: <string> // REQUIRED, default "grpc"
    serverApiVersion: <string> // REQUIRED, default `v3`
    serviceRequestHeadersToAdd: <object-array> // OPTIONAL
      - key: <string>
        value: <string>
    serviceResponseUpstreamHeaders: <string-array> // OPTIONAL
    serviceResponseUpstreamHeadersToAppend: <string-array> // OPTIONAL
    serviceResponseClientHeaders: <string-array> // OPTIONAL
    serviceResponseClientHeadersOnSuccess: <string-array> // OPTIONAL
    pathPrefix: <string> // OPTIONAL
    requestTimeout: <number> // REQUIRED, default `5000`
    includePeerCertificate: <boolean> // REQUIRED, default `false`
    allowedHeaders: <string-array> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI by using this format: <code>h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>grpc</code></p></div></div></td><td><div><div><p>Type of external server. Supported values are <code>grpc</code> and <code>http</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverApiVersion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>v3</code></p></div></div></td><td><div><div><p>Transport protocol API version. Supported values are <code>v3</code> and <code>v2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>includePeerCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>If <code>true</code>, includes peer certificates in the authorization server request. Supported values are <code>true</code> and <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Defines custom headers and their value to inject into the authorization service request. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.value</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Value of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Omni Gateway overwrites coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeadersToAppend</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Omni Gateway appends coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service. Omni Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeadersOnSuccess</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service if the request is successfully authorized. Omni Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>pathPrefix</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p><code>requestTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>5000</code></p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service.</p></div></div></td></tr><tr><td><div><div><p><code>allowedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the client HTTP request to propagate to authorization request. By default, requests sent to gRPC servers include all client headers. Requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

### Resource Configuration Example

In the following configuration, a gRPC authorization service receives a request that includes the
peer certificates and authorization token header:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: h2://ext-authz-grpc-service:9001
    serverType: "grpc"
    includePeerCertificate: "true"
    allowedHeaders:
      - access-token
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>External authorization service URI</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>External authorization server type</p></div></div></td><td><div><div><p>Type of external server.</p></div></div></td></tr><tr><td><div><div><p>Server API version</p></div></div></td><td><div><div><p>Transport protocol API version.</p></div></div></td></tr><tr><td><div><div><p>Include peer certificates in the authorization server request</p></div></div></td><td><div><div><p>Includes peer certificates in the authorization server request.</p></div></div></td></tr><tr><td><div><div><p>Path prefix</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p>Request timeout</p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service. By default, the request timeout is 5000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Allowed headers</p></div></div></td><td><div><div><p>By default, requests sent to gRPC servers include all client headers and requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow during the
External Authorization policy execution:

![A sequence diagram that illustrates the interaction between a user, an API gateway, a database, and an API](/mulesoft/current/en-us/gateway/latest/_images/ext-auth-policy.png)

1.  The client makes an HTTP request to the API instance exposed by Omni Gateway.

2.  Omni Gateway forwards the request consisting of the client’s request and headers to the
    authorization service.

3.  The authorization services sends the authorization response back to Omni Gateway:

    - If the request isn’t authorized, Omni Gateway appends any necessary headers and returns a
      `403` forbidden access code to the client.

    - If the request is authorized, Omni Gateway appends the header data to the client request, if
      necessary, and allows the request to pass to the upstream service.

4.  Omni Gateway appends any necessary headers and returns the response as normal.

<!-- document id=f28af0a859ea2123ee06e50f26fe265baafb1d3138dffb0e451bf64d2c258925 url=/mulesoft/current/en-us/gateway/1.12/policies-included-external-processing.md -->

---
product: Omni Gateway
version: 1.12
keywords: external processing, processing, flex gateway, gateway, policy
---

# External Processing Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>External Processing</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sends the incoming HTTP requests or outgoing HTTP responses requests to an external gRPC service for additional processing</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The External Processing policy forwards the incoming HTTP request or outgoing HTTP response to an
external gRPC service to modify the headers, trailers, body, or any combination of the three. You
can also configure this policy to process either the request, response, or both.

Additionally, the external processing service can request different parts of the HTTP request or
response after the initial gRPC request was sent by Flex Gateway to the external processing server.
This enables you to send the minimum amount of data necessary. For example, Flex Gateway can
initially send only the HTTP requests headers. Then, after some processing, the external processor
can request the HTTP request body or trailers from Flex Gateway.

The parameters you set for sending the HTTP headers, trailers, and body only configure what is
initially sent. The external processing service has access to all parts of the HTTP request or
response regardless of what is configured. Configure the parameters to send all of the information
that the processing service needs for every incoming HTTP request or response. For example, if the
processing service needs the headers for every request but only needs the body for some of the
requests, depending on the information found in the header, only configure the parameters to send
the headers.

The External Processing policy is an extension of the External Processing filter native to Envoy. To
learn more about the External Processing filter, see
[External Processing Filter](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto).
Not all External Processing filter parameters are available for the External Processing policy. To
find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the HTTP request or response, ensure that you order the policies
> depending on if these modification should be present when the request is sent to the processing
> service or upstream service. For more information about ordering policies, see
> [Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder).

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: <string> // REQUIRED
    messageTimeout: <integer> // OPTIONAL, default: 1000
    requestHeaderMode: <string> // OPTIONAL, default: "send"
    responseHeaderMode: <string> // OPTIONAL, default: "send"
    requestBodyMode: <string> // OPTIONAL, default: "none"
    responseBodyMode: <string> // OPTIONAL, default: "none"
    requestTrailerMode: <string> // OPTIONAL, default: "skip"
    responseTrailerMode: <string> // OPTIONAL, default: "skip"
    failureModeAllow: <boolean> // OPTIONAL, default: false
    maxMessageTimeout: <integer> // OPTIONAL, default: 0
    allowModeOverride: <boolean> // OPTIONAL, default: true
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>messageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1000</code></p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p><code>maxMessageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <code>messageTimeout</code>.</p></div></div></td></tr><tr><td><div><div><p><code>failureModeAllow</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p><code>allowModeOverride</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <code>requestHeaderMode</code>, <code>responseHeaderMode</code>, <code>requestBodyMode</code>, <code>responseBodyMode</code>, <code>requestTrailerMode</code>, and <code>responseTrailerMode</code> parameters.</p></div></div></td></tr><tr><td><div><div><p><code>observabilityMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, the configured headers, body, and trailers are sent to the external processing server and Flex Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p><code>requestHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP requests headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP response headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requestBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP request body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>responseBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP response body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>requestTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP requests' trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP response trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

#### Resource Configuration Example

This configuration streams the request headers, trailers, and body to the external processing
server. This configuration does not send any part of the response to the external processing server.

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: h2://<ext.authz.com>:<port>
    messageTimeout: <integer> // OPTIONAL
    responseHeaderMode: skip
    requestBodyMode: streamed
    responseTrailerMode: skip
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>External processing server URI</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Message timeout</p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Max message timeout</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <strong>Message timeout</strong>.</p></div></div></td></tr><tr><td><div><div><p>Failure mode allow</p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p>Allow mode override</p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <strong>Request header processing mode</strong>, <strong>Response header processing mode</strong>, <strong>Request body processing mode</strong>, <strong>Response body processing mode</strong>, <strong>Request trailer processing mode</strong>, and <strong>Response trailer processing mode</strong> parameters.</p></div></div></td></tr><tr><td><div><div><p>Observability mode</p></div></div></td><td><div><div><p>If enabled, the configured headers, body, and trailers are sent to the external processing server and Flex Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p>Request header processing mode</p></div></div></td><td><div><div><p>Whether the requests headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response header processing mode</p></div></div></td><td><div><div><p>Whether the response headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Request body processing mode</p></div></div></td><td><div><div><p>Mode that the request body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Response body processing mode</p></div></div></td><td><div><div><p>Mode that the response body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Request trailer processing mode</p></div></div></td><td><div><div><p>Whether the requests trailers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response trailer processing mode</p></div></div></td><td><div><div><p>Whether the response trailers are sent to the processing service.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow when the External
Processing policy is applied:

![A flowchart illustrating API interaction](/mulesoft/current/en-us/gateway/1.12/_images/ext-processing-policy.png)

1.  The client makes an HTTP request to Flex Gateway.

2.  Flex Gateway forwards the initial parts of the client HTTP request that you configure to the
    external processing service. If **Observability mode** is enabled, the next step is skipped.

3.  Flex Gateway awaits the modified client HTTP request. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the request.

4.  Flex Gateway sends the client HTTP request to the upstream API service and awaits the HTTP
    response.

5.  Flex Gateway forwards the initial parts of the HTTP response that you configure to the external
    processing service. If **Observability mode** is enabled, the next step is skipped.

6.  Flex Gateway awaits the modified HTTP response. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the HTTP response.

7.  Flex Gateway returns the modified HTTP response from the external processing service to the
    client.

By default, if Flex Gateway can’t establish a connection to the gRPC service or if the gRPC service
returns an error, the policy fails. To forward requests regardless of connection or error status,
enable the **Failure mode allow** parameter.

<!-- document id=7462645c83b1d133e69edb9a34cc1034141f637498c27967c2d1996782356bb7 url=/mulesoft/current/en-us/gateway/1.13/policies-included-external-processing.md -->

---
product: Omni Gateway
version: 1.13
keywords: external processing, processing, flex gateway, gateway, policy
---

# External Processing Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>External Processing</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sends the incoming HTTP requests or outgoing HTTP responses requests to an external gRPC service for additional processing</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-processing-release-notes">External Processing</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The External Processing policy forwards the incoming HTTP request or outgoing HTTP response to an
external gRPC service to modify the headers, trailers, body, or any combination of the three. You
can also configure this policy to process either the request, response, or both.

Additionally, the external processing service can request different parts of the HTTP request or
response after the initial gRPC request was sent by Omni Gateway to the external processing server.
This enables you to send the minimum amount of data necessary. For example, Omni Gateway can
initially send only the HTTP requests headers. Then, after some processing, the external processor
can request the HTTP request body or trailers from Omni Gateway.

The parameters you set for sending the HTTP headers, trailers, and body only configure what is
initially sent. The external processing service has access to all parts of the HTTP request or
response regardless of what is configured. Configure the parameters to send all of the information
that the processing service needs for every incoming HTTP request or response. For example, if the
processing service needs the headers for every request but only needs the body for some of the
requests, depending on the information found in the header, only configure the parameters to send
the headers.

The External Processing policy is an extension of the External Processing filter native to Envoy. To
learn more about the External Processing filter, see
[External Processing Filter](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto).
Not all External Processing filter parameters are available for the External Processing policy. To
find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the HTTP request or response, ensure that you order the policies
> depending on if these modification should be present when the request is sent to the processing
> service or upstream service. For more information about ordering policies, see
> [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: <string> // REQUIRED
    messageTimeout: <integer> // OPTIONAL, default: 1000
    requestHeaderMode: <string> // OPTIONAL, default: "send"
    responseHeaderMode: <string> // OPTIONAL, default: "send"
    requestBodyMode: <string> // OPTIONAL, default: "none"
    responseBodyMode: <string> // OPTIONAL, default: "none"
    requestTrailerMode: <string> // OPTIONAL, default: "skip"
    responseTrailerMode: <string> // OPTIONAL, default: "skip"
    failureModeAllow: <boolean> // OPTIONAL, default: false
    maxMessageTimeout: <integer> // OPTIONAL, default: 0
    allowModeOverride: <boolean> // OPTIONAL, default: true
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>messageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1000</code></p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p><code>maxMessageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <code>messageTimeout</code>.</p></div></div></td></tr><tr><td><div><div><p><code>failureModeAllow</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p><code>allowModeOverride</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <code>requestHeaderMode</code>, <code>responseHeaderMode</code>, <code>requestBodyMode</code>, <code>responseBodyMode</code>, <code>requestTrailerMode</code>, and <code>responseTrailerMode</code> parameters.</p></div></div></td></tr><tr><td><div><div><p><code>observabilityMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, the configured headers, body, and trailers are sent to the external processing server and Omni Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p><code>requestHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP requests headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP response headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requestBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP request body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>responseBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP response body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>requestTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP requests' trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP response trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

#### Resource Configuration Example

This configuration streams the request headers, trailers, and body to the external processing
server. This configuration does not send any part of the response to the external processing server.

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: h2://<ext.authz.com>:<port>
    messageTimeout: <integer> // OPTIONAL
    responseHeaderMode: skip
    requestBodyMode: streamed
    responseTrailerMode: skip
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>External processing server URI</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Message timeout</p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Max message timeout</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <strong>Message timeout</strong>.</p></div></div></td></tr><tr><td><div><div><p>Failure mode allow</p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p>Allow mode override</p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <strong>Request header processing mode</strong>, <strong>Response header processing mode</strong>, <strong>Request body processing mode</strong>, <strong>Response body processing mode</strong>, <strong>Request trailer processing mode</strong>, and <strong>Response trailer processing mode</strong> parameters.</p></div></div></td></tr><tr><td><div><div><p>Observability mode</p></div></div></td><td><div><div><p>If enabled, the configured headers, body, and trailers are sent to the external processing server and Omni Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p>Request header processing mode</p></div></div></td><td><div><div><p>Whether the requests headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response header processing mode</p></div></div></td><td><div><div><p>Whether the response headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Request body processing mode</p></div></div></td><td><div><div><p>Mode that the request body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Response body processing mode</p></div></div></td><td><div><div><p>Mode that the response body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Request trailer processing mode</p></div></div></td><td><div><div><p>Whether the requests trailers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response trailer processing mode</p></div></div></td><td><div><div><p>Whether the response trailers are sent to the processing service.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow when the External
Processing policy is applied:

![A flowchart illustrating API interaction](/mulesoft/current/en-us/gateway/1.13/_images/ext-processing-policy.png)

1.  The client makes an HTTP request to Omni Gateway.

2.  Omni Gateway forwards the initial parts of the client HTTP request that you configure to the
    external processing service. If **Observability mode** is enabled, the next step is skipped.

3.  Omni Gateway awaits the modified client HTTP request. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the request.

4.  Omni Gateway sends the client HTTP request to the upstream API service and awaits the HTTP
    response.

5.  Omni Gateway forwards the initial parts of the HTTP response that you configure to the external
    processing service. If **Observability mode** is enabled, the next step is skipped.

6.  Omni Gateway awaits the modified HTTP response. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the HTTP response.

7.  Omni Gateway returns the modified HTTP response from the external processing service to the
    client.

By default, if Omni Gateway can’t establish a connection to the gRPC service or if the gRPC service
returns an error, the policy fails. To forward requests regardless of connection or error status,
enable the **Failure mode allow** parameter.

<!-- document id=e1bc05f83882cd10767c3543e1dfc929f5c6c9f0ea082cf69074031c503a953a url=/mulesoft/current/en-us/gateway/1.9/policies-included-external-processing.md -->

---
product: Omni Gateway
version: 1.9
keywords: external processing, processing, flex gateway, gateway, policy
---

# External Processing Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>External Processing</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sends the incoming HTTP requests or outgoing HTTP responses requests to an external gRPC service for additional processing</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The External Processing policy forwards the incoming HTTP request or outgoing HTTP response to an
external gRPC service to modify the headers, trailers, body, or any combination of the three. You
can also configure this policy to process either the request, response, or both.

Additionally, the external processing service can request different parts of the HTTP request or
response after the initial gRPC request was sent by Flex Gateway to the external processing server.
This enables you to send the minimum amount of data necessary. For example, Flex Gateway can
initially send only the HTTP requests headers. Then, after some processing, the external processor
can request the HTTP request body or trailers from Flex Gateway.

The parameters you set for sending the HTTP headers, trailers, and body only configure what is
initially sent. The external processing service has access to all parts of the HTTP request or
response regardless of what is configured. Configure the parameters to send all of the information
that the processing service needs for every incoming HTTP request or response. For example, if the
processing service needs the headers for every request but only needs the body for some of the
requests, depending on the information found in the header, only configure the parameters to send
the headers.

The External Processing policy is an extension of the External Processing filter native to Envoy. To
learn more about the External Processing filter, see
[External Processing Filter](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto).
Not all External Processing filter parameters are available for the External Processing policy. To
find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the HTTP request or response, ensure that you order the policies
> depending on if these modification should be present when the request is sent to the processing
> service or upstream service. For more information about ordering policies, see
> [Ordering Policies](https://docs.mulesoft.com/gateway/1.9/policies-reorder).

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: <string> // REQUIRED
    messageTimeout: <integer> // OPTIONAL, default: 1000
    requestHeaderMode: <string> // OPTIONAL, default: "send"
    responseHeaderMode: <string> // OPTIONAL, default: "send"
    requestBodyMode: <string> // OPTIONAL, default: "none"
    responseBodyMode: <string> // OPTIONAL, default: "none"
    requestTrailerMode: <string> // OPTIONAL, default: "skip"
    responseTrailerMode: <string> // OPTIONAL, default: "skip"
    failureModeAllow: <boolean> // OPTIONAL, default: false
    maxMessageTimeout: <integer> // OPTIONAL, default: 0
    allowModeOverride: <boolean> // OPTIONAL, default: true
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>messageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1000</code></p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p><code>maxMessageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <code>messageTimeout</code>.</p></div></div></td></tr><tr><td><div><div><p><code>failureModeAllow</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p><code>allowModeOverride</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <code>requestHeaderMode</code>, <code>responseHeaderMode</code>, <code>requestBodyMode</code>, <code>responseBodyMode</code>, <code>requestTrailerMode</code>, and <code>responseTrailerMode</code> parameters.</p></div></div></td></tr><tr><td><div><div><p><code>observabilityMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, the configured headers, body, and trailers are sent to the external processing server and Flex Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p><code>requestHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP requests headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP response headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requestBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP request body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>responseBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP response body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>requestTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP requests' trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP response trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

#### Resource Configuration Example

This configuration streams the request headers, trailers, and body to the external processing
server. This configuration does not send any part of the response to the external processing server.

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: h2://<ext.authz.com>:<port>
    messageTimeout: <integer> // OPTIONAL
    responseHeaderMode: skip
    requestBodyMode: streamed
    responseTrailerMode: skip
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>External processing server URI</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Message timeout</p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Max message timeout</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <strong>Message timeout</strong>.</p></div></div></td></tr><tr><td><div><div><p>Failure mode allow</p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p>Allow mode override</p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <strong>Request header processing mode</strong>, <strong>Response header processing mode</strong>, <strong>Request body processing mode</strong>, <strong>Response body processing mode</strong>, <strong>Request trailer processing mode</strong>, and <strong>Response trailer processing mode</strong> parameters.</p></div></div></td></tr><tr><td><div><div><p>Observability mode</p></div></div></td><td><div><div><p>If enabled, the configured headers, body, and trailers are sent to the external processing server and Flex Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p>Request header processing mode</p></div></div></td><td><div><div><p>Whether the requests headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response header processing mode</p></div></div></td><td><div><div><p>Whether the response headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Request body processing mode</p></div></div></td><td><div><div><p>Mode that the request body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Response body processing mode</p></div></div></td><td><div><div><p>Mode that the response body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Request trailer processing mode</p></div></div></td><td><div><div><p>Whether the requests trailers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response trailer processing mode</p></div></div></td><td><div><div><p>Whether the response trailers are sent to the processing service.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow when the External
Processing policy is applied:

![A flowchart illustrating API interaction](/mulesoft/current/en-us/gateway/1.9/_images/ext-processing-policy.png)

1.  The client makes an HTTP request to Flex Gateway.

2.  Flex Gateway forwards the initial parts of the client HTTP request that you configure to the
    external processing service. If **Observability mode** is enabled, the next step is skipped.

3.  Flex Gateway awaits the modified client HTTP request. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the request.

4.  Flex Gateway sends the client HTTP request to the upstream API service and awaits the HTTP
    response.

5.  Flex Gateway forwards the initial parts of the HTTP response that you configure to the external
    processing service. If **Observability mode** is enabled, the next step is skipped.

6.  Flex Gateway awaits the modified HTTP response. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the HTTP response.

7.  Flex Gateway returns the modified HTTP response from the external processing service to the
    client.

By default, if Flex Gateway can’t establish a connection to the gRPC service or if the gRPC service
returns an error, the policy fails. To forward requests regardless of connection or error status,
enable the **Failure mode allow** parameter.

<!-- document id=32d772b2180483701230d549f35dc187073ff40ca7d74f32bd72dd86bf3da2fe url=/mulesoft/current/en-us/gateway/latest/policies-included-external-processing.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: external processing, processing, flex gateway, gateway, policy
---

# External Processing Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>External Processing</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sends the incoming HTTP requests or outgoing HTTP responses requests to an external gRPC service for additional processing</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-processing-release-notes">External Processing</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The External Processing policy forwards the incoming HTTP request or outgoing HTTP response to an
external gRPC service to modify the headers, trailers, body, or any combination of the three. You
can also configure this policy to process either the request, response, or both.

Additionally, the external processing service can request different parts of the HTTP request or
response after the initial gRPC request was sent by Omni Gateway to the external processing server.
This enables you to send the minimum amount of data necessary. For example, Omni Gateway can
initially send only the HTTP requests headers. Then, after some processing, the external processor
can request the HTTP request body or trailers from Omni Gateway.

The parameters you set for sending the HTTP headers, trailers, and body only configure what is
initially sent. The external processing service has access to all parts of the HTTP request or
response regardless of what is configured. Configure the parameters to send all of the information
that the processing service needs for every incoming HTTP request or response. For example, if the
processing service needs the headers for every request but only needs the body for some of the
requests, depending on the information found in the header, only configure the parameters to send
the headers.

The External Processing policy is an extension of the External Processing filter native to Envoy. To
learn more about the External Processing filter, see
[External Processing Filter](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/ext_proc.proto).
Not all External Processing filter parameters are available for the External Processing policy. To
find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the HTTP request or response, ensure that you order the policies
> depending on if these modification should be present when the request is sent to the processing
> service or upstream service. For more information about ordering policies, see
> [Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: <string> // REQUIRED
    messageTimeout: <integer> // OPTIONAL, default: 1000
    requestHeaderMode: <string> // OPTIONAL, default: "send"
    responseHeaderMode: <string> // OPTIONAL, default: "send"
    requestBodyMode: <string> // OPTIONAL, default: "none"
    responseBodyMode: <string> // OPTIONAL, default: "none"
    requestTrailerMode: <string> // OPTIONAL, default: "skip"
    responseTrailerMode: <string> // OPTIONAL, default: "skip"
    failureModeAllow: <boolean> // OPTIONAL, default: false
    maxMessageTimeout: <integer> // OPTIONAL, default: 0
    allowModeOverride: <boolean> // OPTIONAL, default: true
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>messageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1000</code></p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p><code>maxMessageTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <code>messageTimeout</code>.</p></div></div></td></tr><tr><td><div><div><p><code>failureModeAllow</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p><code>allowModeOverride</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <code>requestHeaderMode</code>, <code>responseHeaderMode</code>, <code>requestBodyMode</code>, <code>responseBodyMode</code>, <code>requestTrailerMode</code>, and <code>responseTrailerMode</code> parameters.</p></div></div></td></tr><tr><td><div><div><p><code>observabilityMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>When <code>true</code>, the configured headers, body, and trailers are sent to the external processing server and Omni Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p><code>requestHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP requests headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseHeaderMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>send</code></p></div></div></td><td><div><div><p>Whether the HTTP response headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>requestBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP request body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>responseBodyMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>none</code></p></div></div></td><td><div><div><p>Mode that the HTTP response body is sent in. Supported values are <code>none</code>, <code>streamed</code>, <code>buffered</code>, and <code>bufferedPartial</code>. Selecting <code>none</code> does not send the request body.</p></div></div></td></tr><tr><td><div><div><p><code>requestTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP requests' trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr><tr><td><div><div><p><code>responseTrailerMode</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>skip</code></p></div></div></td><td><div><div><p>Whether the HTTP response trailer headers are sent to the processing service. Supported values are <code>send</code> and <code>skip</code>.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

#### Resource Configuration Example

This configuration streams the request headers, trailers, and body to the external processing
server. This configuration does not send any part of the response to the external processing server.

```yaml
- policyRef:
    name: native-ext-proc-flex
  config:
    uri: h2://<ext.authz.com>:<port>
    messageTimeout: <integer> // OPTIONAL
    responseHeaderMode: skip
    requestBodyMode: streamed
    responseTrailerMode: skip
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>External processing server URI</p></div></div></td><td><div><div><p>External processing server URI. For gRPC type servers, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>Message timeout</p></div></div></td><td><div><div><p>Message timeout for the processing server in milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Max message timeout</p></div></div></td><td><div><div><p>Specifies the upper bound the processing server can override <strong>Message timeout</strong>.</p></div></div></td></tr><tr><td><div><div><p>Failure mode allow</p></div></div></td><td><div><div><p>When <code>true</code>, if the gRPC stream prematurely closes or can’t be opened, request processing continues without error.</p></div></div></td></tr><tr><td><div><div><p>Allow mode override</p></div></div></td><td><div><div><p>Enables the processing server to override the policy configuration. When <code>true</code>, the server can override the configuration of the <strong>Request header processing mode</strong>, <strong>Response header processing mode</strong>, <strong>Request body processing mode</strong>, <strong>Response body processing mode</strong>, <strong>Request trailer processing mode</strong>, and <strong>Response trailer processing mode</strong> parameters.</p></div></div></td></tr><tr><td><div><div><p>Observability mode</p></div></div></td><td><div><div><p>If enabled, the configured headers, body, and trailers are sent to the external processing server and Omni Gateway doesn’t wait for a response from the processing server.</p></div></div></td></tr><tr><td><div><div><p>Request header processing mode</p></div></div></td><td><div><div><p>Whether the requests headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response header processing mode</p></div></div></td><td><div><div><p>Whether the response headers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Request body processing mode</p></div></div></td><td><div><div><p>Mode that the request body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Response body processing mode</p></div></div></td><td><div><div><p>Mode that the response body is sent in.</p></div></div></td></tr><tr><td><div><div><p>Request trailer processing mode</p></div></div></td><td><div><div><p>Whether the requests trailers are sent to the processing service.</p></div></div></td></tr><tr><td><div><div><p>Response trailer processing mode</p></div></div></td><td><div><div><p>Whether the response trailers are sent to the processing service.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a value blank configures the parameter with the default value. If a required
> parameter doesn’t have a default value, you must configure the parameter.

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow when the External
Processing policy is applied:

![A flowchart illustrating API interaction](/mulesoft/current/en-us/gateway/latest/_images/ext-processing-policy.png)

1.  The client makes an HTTP request to Omni Gateway.

2.  Omni Gateway forwards the initial parts of the client HTTP request that you configure to the
    external processing service. If **Observability mode** is enabled, the next step is skipped.

3.  Omni Gateway awaits the modified client HTTP request. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the request.

4.  Omni Gateway sends the client HTTP request to the upstream API service and awaits the HTTP
    response.

5.  Omni Gateway forwards the initial parts of the HTTP response that you configure to the external
    processing service. If **Observability mode** is enabled, the next step is skipped.

6.  Omni Gateway awaits the modified HTTP response. If **Allow mode override** is enabled, the
    external processing service can request additional parts of the HTTP response.

7.  Omni Gateway returns the modified HTTP response from the external processing service to the
    client.

By default, if Omni Gateway can’t establish a connection to the gRPC service or if the gRPC service
returns an error, the policy fails. To forward requests regardless of connection or error status,
enable the **Failure mode allow** parameter.

<!-- document id=894eca2fe30099618ff174f8362b5fb1030f7ef9fb6b90fb78f76c5e63ab2c24 url=/mulesoft/current/en-us/gateway/latest/policies-included-f5-guardrails.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, content safety, f5, calypsoai, guardrails, redaction
---

# F5 Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>F5 Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates LLM prompts and responses against F5 AI Guardrails, blocking, flagging, or redacting flagged content</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.14.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/f5-guardrails-release-notes">F5 Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>200 - OK: Content blocked by F5 AI Guardrails. The response is a native content-filter response for the caller’s LLM format.</p></td></tr><tr><td><p>503 - Service Unavailable: F5 scan call failed or returned no verdict (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The F5 Guardrails policy provides content moderation for LLMs by evaluating prompts and responses
against [F5 AI Guardrails](https://docs.aisecurity.f5.com/). The policy calls the F5
(`POST /backend/v1/scans`) API and enforces the returned verdict at the gateway before the request
reaches the upstream LLM (request phase) or before the response is returned to the client (response
phase).

Which F5 scanners run and how they behave (harmful content, prompt injection, PII and other
sensitive data, data leakage, and so on) is owned by your F5 project configuration, not the policy.
The policy is the enforcement point that turns an F5 verdict into a gateway action:

- **Allow**: Cleared content is forwarded unchanged.

- **Flag**: Flagged content is allowed but a policy violation is recorded (audit).

- **Redact**: Sensitive content is masked in place using F5’s redaction, then forwarded.

- **Reject**: Blocked content is rejected. The client receives a native content-filter response for
  its LLM format (OpenAI, Anthropic, or Gemini) with HTTP status `200`.

The policy operates in two independent phases:

- **Request phase**: Sends the whole request body to F5 with `scanDirection: request`. Rejected
  prompts never reach the LLM.

- **Response phase**: Sends the whole LLM response body to F5 with `scanDirection: response` before
  returning it to the client. This response phase is off by default.

Every scan emits observability headers, a scan ID for correlation with the F5 console, a per-call
metric, and records a policy violation for the **Flag** or **Reject** outcomes.

## Before You Begin

Before configuring this policy, you need:

1.  **F5 AI Guardrails access** (SaaS tenant or a self-hosted deployment).

2.  **An F5 AI Guardrails endpoint URL**, for example, `https://us1.calypsoai.app`.

3.  **An F5 API token** issued from the F5 console.

4.  **(Optional) An F5 project ID or friendly ID** whose F5 scanner configuration the scan should
    use.

If you connect to F5 SaaS, ensure the Omni Gateway can reach the F5 host outbound.

The policy reads the `x-input-format` header, which the LLM proxy sets, to identify the caller’s LLM
format: `openai`, `anthropic`, or `gemini`. If the header is absent, the policy uses `openai`.
Traffic with any other format value, or a non-JSON body, passes through unscanned.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The F5 Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>F5 AI Guardrails Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>F5 AI Guardrails base URL, for example, <code>https://us1.calypsoai.app</code>. The policy appends <code>/backend/v1/scans</code> at call time.</p></div></div></td></tr><tr><td><div><div><p>F5 API Token</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>F5 AI Guardrails API token. Enter the raw token without a <code>Bearer</code> prefix. The policy sends it as <code>Authorization: Bearer &lt;token&gt;</code> on every scan call. This value is sensitive and is never logged.</p></div></div></td></tr><tr><td><div><div><p>F5 Project</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>F5 project ID or friendly ID. When set, it’s sent as the <code>project</code> field so the scan uses that project’s F5 scanner configuration. When omitted, the token’s globally available F5 scanners are used.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default), the policy evaluates the user prompt against F5 AI Guardrails (<code>scanDirection: request</code>) before forwarding to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, the policy evaluates the LLM response (<code>scanDirection: response</code>) before returning it to the client. Default: disabled.</p></div><div><p>Streaming responses (<code>text/event-stream</code>) are also scanned. The policy buffers the entire stream and holds the response until the scan completes. This breaks the streaming experience for the client and increases latency and memory use.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Apply Redaction</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default), a <code>redacted</code> outcome rewrites the request or response body with the F5-supplied masked text and lets traffic continue. When disabled, a <code>redacted</code> outcome is handled like a <code>blocked</code> outcome and rejected with a native content-filter response (HTTP <code>200</code>). See <a href="#outcomes-and-actions">Outcomes and Actions</a>.</p></div></div></td></tr><tr><td><div><div><p>Flag Only (Audit Mode)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, the scan carries <code>flagOnly: true</code> so blockable F5 scanners return <code>flagged</code> instead of <code>blocked</code>, and the policy never rejects for an F5 scanner hit. A policy violation is still recorded. Use this to observe what F5 would block without enforcing. Default: disabled.</p></div></div></td></tr><tr><td><div><div><p>Disabled Scanners</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>F5 scanner IDs to disable, sent as the <code>disabled</code> array. Applies to both phases unless overridden per phase by Request-Phase or Response-Phase Scanner Overrides. Overrides the project or token defaults for the named F5 scanners.</p></div></div></td></tr><tr><td><div><div><p>Force-Enabled Scanners</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>F5 scanner IDs to force-enable, sent as the <code>forceEnabled</code> array, even if disabled in the project. Applies to both phases unless overridden per phase.</p></div></div></td></tr><tr><td><div><div><p>Request-Phase Scanner Overrides</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-phase F5 scanner selection for the request (prompt) scan, with optional <code>disabledScanners</code> and <code>forceEnabledScanners</code> arrays. See <a href="#per-phase-scanner-selection">Per-Phase Scanner Selection</a>.</p></div></div></td></tr><tr><td><div><div><p>Response-Phase Scanner Overrides</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-phase F5 scanner selection for the response (completion) scan. Same shape as Request-Phase Scanner Overrides. See <a href="#per-phase-scanner-selection">Per-Phase Scanner Selection</a>.</p></div></div></td></tr><tr><td><div><div><p>Verbose</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, the policy requests more detailed scanner results from F5. The extra detail enriches the reason header and debug logs. Default: disabled.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-request timeout for each F5 scan call in milliseconds. Must be between <code>1000</code> and <code>30000</code>. Default: <code>5000</code>.</p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the F5 scan call fails, times out, or returns no verdict:</p></div><div><ul><li><p>Disabled (default): Rejects with HTTP <code>503</code>.</p></li><li><p>Enabled: Allows traffic to proceed unscanned (fail-open mode).</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The F5 Guardrails policy integrates with F5 AI Guardrails to evaluate LLM prompts and responses.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when Moderate Request is enabled):

    1.  The policy resolves the caller’s LLM format from the `x-input-format` header. Traffic in an
        unsupported format, or with a non-JSON or empty body, passes through unscanned.

    2.  The policy sends the whole request body to `POST {endpoint}/backend/v1/scans` with
        `scanDirection: request`.

    3.  The policy enforces the returned outcome. See [Outcomes and Actions](#outcomes-and-actions).

    4.  If the prompt passes (cleared or flagged), the policy forwards the request to the upstream
        LLM. On `redacted`, it forwards a masked version. On `blocked`, it returns a native
        content-filter response with HTTP `200`.

2.  **Response Phase** (when Moderate Response is enabled):

    1.  The policy buffers the LLM response.

    2.  The policy sends the whole response body to F5 with `scanDirection: response`.

    3.  The policy enforces the returned outcome. See [Outcomes and Actions](#outcomes-and-actions).

    4.  If the response passes, the policy forwards it unchanged. On `redacted`, the body is
        rewritten with the masked body. On `blocked`, the response is rewritten to a native
        content-filter response with HTTP `200`.

        > [!NOTE] Streaming responses (`text/event-stream`) are buffered and scanned when Moderate
        > Response is enabled. The client doesn’t receive the response until the scan completes.

When both phases scan, the client-visible response headers reflect the response-phase decision. They
reflect the request-phase decision only when the response isn’t scanned.

### Outcomes and Actions

The policy enforces the global `result.outcome` returned by F5:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>F5 Outcome</th><th>Action</th><th>Effect</th></tr></thead><tbody><tr><td><div><div><p><code>cleared</code></p></div></div></td><td><div><div><p>Allow</p></div></div></td><td><div><div><p>Content is forwarded unchanged. No policy violation recorded.</p></div></div></td></tr><tr><td><div><div><p><code>flagged</code></p></div></div></td><td><div><div><p>Flag</p></div></div></td><td><div><div><p>Traffic continues, a policy violation is recorded, and the failed F5 scanner names populate the reason header. This is the outcome for audit (non-blocking) F5 scanners and for every blockable F5 scanner when <strong>Flag Only</strong> is enabled.</p></div></div></td></tr><tr><td><div><div><p><code>redacted</code></p></div></div></td><td><div><div><p>Redact</p></div></div></td><td><div><div><p>When Apply Redaction is enabled (default), the whole request or response body is replaced with the masked body that F5 returns, traffic continues, and a policy violation is recorded. If F5 returns no masked body, the policy fails closed and rejects the content with the reason <code>redaction_failed</code>. When Apply Redaction is disabled, the outcome is treated as <code>blocked</code>.</p></div></div></td></tr><tr><td><div><div><p><code>blocked</code></p></div></div></td><td><div><div><p>Reject</p></div></div></td><td><div><div><p>The request phase returns a native content-filter response instead of calling the LLM; the response phase rewrites the LLM response to a native content-filter response. Both use HTTP <code>200</code>. A policy violation is recorded. Any unrecognized outcome is also treated as <code>blocked</code> so an unexpected verdict never silently passes.</p></div></div></td></tr><tr><td><div><div><p><code>none</code> (no verdict)</p></div></div></td><td><div><div><p>Indeterminate</p></div></div></td><td><div><div><p>An empty or <code>none</code> outcome isn’t treated as a block. It’s resolved by the Fail Open setting: fail-closed returns an HTTP <code>503</code> error with the reason <code>none_response</code>, fail-open passes traffic through unscanned.</p></div></div></td></tr></tbody></table>

Every non-`cleared` outcome records a policy violation and adds the failed F5 scanner names to the
reason header.

### Per-Phase Scanner Selection

The `disabled` and `forceEnabled` F5 scanner lists sent on each scan are resolved per phase, so the
request (prompt) and response (completion) phases can target different F5 scanner sets:

- The **request phase** uses Request-Phase Scanner Overrides when set, otherwise the global
  **Disabled Scanners** and **Force-Enabled Scanners** lists.

- The **response phase** uses response-phase scanner overrides with the same global fallback.

- Each list falls back independently. An explicitly empty per-phase array (`[]`) replaces (clears)
  the global list for that phase; an unset array falls back to the global list.

When neither per-phase override is set, the global lists apply to both phases. If a per-phase
override is set for a phase whose moderation is disabled, the override can never take effect, and
the policy logs a startup warning.

## Example Configurations

### Minimal Configuration — Both Phases, Enforce and Redact

`moderateRequest` and `applyRedaction` default to `true`, so the prompt is scanned, sensitive data
is masked in place on a `redacted` verdict, and blocked content returns a native content-filter
response. `moderateResponse` defaults to `false`. Add it to also scan the LLM response.

```yaml
- policyRef:
    name: f5-guardrails-policy-v1-0-impl
    namespace: default
  config:
    f5Endpoint: https://us1.calypsoai.app
    f5ApiToken: "${F5_GUARDRAILS_TOKEN}"
    f5Project: "<your-f5-project-id>"
```

### Audit Mode — Observe Without Enforcing

No request is ever blocked. Every F5 scanner hit surfaces as `flag` with a policy violation and
reason header. Use this to measure impact before switching to enforcement.

```yaml
- policyRef:
    name: f5-guardrails-policy-v1-0-impl
    namespace: default
  config:
    f5Endpoint: https://us1.calypsoai.app
    f5ApiToken: "${F5_GUARDRAILS_TOKEN}"
    f5Project: "<your-f5-project-id>"
    advancedConfiguration:
      flagOnly: true
      applyRedaction: false
```

### Request-Only, Fail-Open, Custom Scanners

Only the prompt is scanned, one F5 scanner is disabled for this route, and if F5 is unreachable the
request proceeds unscanned (with the reason header emitted).

```yaml
- policyRef:
    name: f5-guardrails-policy-v1-0-impl
    namespace: default
  config:
    f5Endpoint: https://eu1.calypsoai.app
    f5ApiToken: "${F5_GUARDRAILS_TOKEN}"
    f5Project: "prod-chat"
    moderateRequest: true
    moderateResponse: false
    advancedConfiguration:
      disabledScanners: ["01983d0c-f1cc-700a-ab56-6600efc7dfb9"]
      apiTimeoutMs: 8000
      failOpen: true
```

### Per-Phase Scanner Selection

The request scan and response scan target independent F5 scanner sets. The request phase clears the
global disable list and force-enables an F5 scanner; the response phase keeps the global disable and
adds another F5 scanner.

```yaml
- policyRef:
    name: f5-guardrails-policy-v1-0-impl
    namespace: default
  config:
    f5Endpoint: https://us1.calypsoai.app
    f5ApiToken: "${F5_GUARDRAILS_TOKEN}"
    f5Project: "prod-chat"
    advancedConfiguration:
      disabledScanners: ["01983d0c-f1cc-700a-ab56-6600efc7dfb9"]
      requestScanners:
        disabledScanners: []
        forceEnabledScanners: ["019f3a1b-2c3d-4e5f-6071-8293a4b5c6d7"]
      responseScanners:
        forceEnabledScanners: ["01a2b3c4-d5e6-7089-abcd-ef0123456789"]
```

## See Also

- [F5 AI Guardrails documentation](https://docs.aisecurity.f5.com/)

- [Azure Content Safety Policy](https://docs.mulesoft.com/gateway/latest/policies-included-azure-content-safety)

- [Amazon Bedrock Guardrails Policy](https://docs.mulesoft.com/gateway/latest/policies-included-bedrock-guardrails)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies)

<!-- document id=a9308d116bc373f65c4ce5efbb1b4929750d922da70d0c1f4110bf35e0955145 url=/mulesoft/current/en-us/gateway/1.12/flex-agent-policies.md -->

---
product: Omni Gateway
version: 1.12
---

# Flex Gateway Agent Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Flex Gateway processes requests, enabling you to secure and govern your
server instances. Flex Gateway includes A2A and MCP specific policies that provide enhanced security
and control over agent interactions.

To apply a policy, see
[Applying Policies for Managed Flex Gateways and Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-secure-conn).

Flex Gateway MCP and A2A server instances also support other Flex Gateway policies to protect server
instances through rate limiting, authentication, authorization, threat protection, monitoring, and
logging. For more information about MuleSoft-provided policies, see the
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements. For information about creating custom policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

> [!NOTE] All agent policies are inbound policies and are not supported as automated policies.

## SSE Policies

Both A2A and MCP support the following policies for Server-Sent Events (SSE) streaming:

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-sse-logging">SSE Logging</a></p></td><td><p>Logs every SSE event while streaming</p></td></tr></tbody></table>

## A2A Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-agent-card">A2A Agent Card</a></p></td><td><p>Rewrites the Agent Card URL to match the server instance public URL</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-pii-detector">A2A PII Detector</a></p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-prompt-decorator">A2A Prompt Decorator</a></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-schema-validation">A2A Schema Validation</a></p></td><td><p>Validates agent requests to ensure they conform to the A2A specification</p></td></tr></tbody></table>

## MCP Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-attribute-access-control">MCP Attribute-Based Access Control</a></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-global-access">MCP Global Access</a></p></td><td><p>Restricts which MCP tools are exposed by defining Allow and Block rules</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-pii-detector">MCP PII Detector</a></p></td><td><p>Blocks elicitation responses containing personally identifiable information (PII) from reaching MCP servers</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-payload-optimization">MCP Payload Optimization</a></p></td><td><p>Optimizes MCP tool responses for token consumption by transforming HTML to Markdown and removing unnecessary data</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-schema-validation">MCP Schema Validation</a></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-support">MCP Support</a></p></td><td><p>Adds MCP support to a Flex Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-tool-mapping">MCP Tool Mapping</a></p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr></tbody></table>

## See Also

- [Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder)

- [DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support)

<!-- document id=26f79991bc7c5a717d8c6dbc2d31dbbb2913509da3b0c8cc9b2566a340244741 url=/mulesoft/current/en-us/gateway/1.9/flex-agent-policies.md -->

---
product: Omni Gateway
version: 1.9
---

# Flex Gateway Agent Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Flex Gateway processes requests, enabling you to secure and govern your
server instances. Flex Gateway includes A2A and MCP specific policies that provide enhanced security
and control over agent interactions.

To apply a policy, see
[Applying Policies for Managed Flex Gateways and Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-secure-conn).

Flex Gateway MCP and A2A server instances also support other Flex Gateway policies to protect server
instances through rate limiting, authentication, authorization, threat protection, monitoring, and
logging. For more information about MuleSoft-provided policies, see the
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements. For information about creating custom policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

> [!NOTE] All agent policies are inbound policies and are not supported as automated policies.

## SSE Policies

Both A2A and MCP support the following policies for Server-Sent Events (SSE) streaming:

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-sse-logging">SSE Logging</a></p></td><td><p>Logs every SSE event while streaming</p></td></tr></tbody></table>

## A2A Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-agent-card">A2A Agent Card</a></p></td><td><p>Rewrites the Agent Card URL to match the server instance public URL</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-pii-detector">A2A PII Detector</a></p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-prompt-decorator">A2A Prompt Decorator</a></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-schema-validation">A2A Schema Validation</a></p></td><td><p>Validates agent requests to ensure they conform to the A2A specification</p></td></tr></tbody></table>

## MCP Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-mcp-attribute-access-control">MCP Attribute-Based Access Control</a></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-mcp-schema-validation">MCP Schema Validation</a></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-mcp-support">MCP Support</a></p></td><td><p>Adds MCP support to a Flex Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr></tbody></table>

## See Also

- [Ordering Policies](https://docs.mulesoft.com/gateway/1.9/policies-reorder)

- [DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.9/policies-flex-dataweave-support)

<!-- document id=5404b77e536303da0ac735627ababdd9e5049f9218cb534943da5beb8f9a9c61 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-basic-deployments.md -->

---
product: Omni Gateway
version: 1.12
---

# Flex Gateway Deployment Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports multiple deployment models, which apply to both Connected Mode and Local Mode:

- [Standalone deployment](#standalone-deployment)

- [Ingress deployment](#ingress-deployment)

- [Egress deployment](#egress-deployment)

- [Sidecar deployment](#sidecar-deployment)

You can extend the deployment models in this overview to all technological stacks that have the
appropriate network controls applied. For more information about routing configuration modes, see
[Routing Configuration Methods](#routing-configuration-methods).

All the following diagrams show Flex Gateway running in Connected Mode. For Flex Gateway running in
Local Mode, the only difference is that Anypoint Platform would not be present in the deployment
model. This does not affect how information flows between Flex Gateway and the upstream and
downstream services.

## Standalone Deployment

In a standalone deployment, Flex Gateway acts as a standalone service that protects one or more
integration API flows by managing internal traffic.

As the following diagram shows, all traffic is inside an organization-owned network. The traffic
passes through Flex Gateway before reaching the consumer APIs.

![In a standalone deployment, Flex Gateway and the consumer applications are in the same network.](/mulesoft/current/en-us/gateway/1.12/_images/ad-standalone-deployment.png)

## Ingress Deployment

Similar to standalone deployment, in an ingress deployment, Flex Gateway acts as a standalone
service that protects one or more integration API flows. However, in an ingress deployment, Flex
Gateway manages external traffic entering the internal network. Ingress deployment is the most
common deployment model.

Flex Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all external traffic passes through Flex Gateway before reaching the
consumer APIs. Flex Gateway is typically deployed behind a load balancer, and the consumer
application does not belong to the same network as Flex Gateway or the APIs.

![In an ingress deployment, Flex Gateway and the consumer applications are in different networks.](/mulesoft/current/en-us/gateway/1.12/_images/ad-ingress-deployment.png)

> [!NOTE] Ingress deployment is not the same as a Kubernetes Ingress controller or Ingress
> `Resource`. For more information about routing configuration, see
> [Routing Configuration Methods](#routing-configuration-methods).

## Egress Deployment

An egress deployment is the opposite deployment model of an ingress deployment. Flex Gateway still
acts as a standalone service that protects one or more integration API flows. However, in an egress
deployment, Flex Gateway manages internal traffic exiting the internal network, for example, API
requests to non-organization-owned APIs.

Flex Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all internal traffic from the consumer application passes through
Flex Gateway before reaching the external APIs.

![A diagram of Anypoint Platform depicting the flow of data between the platform, a Flex Gateway, APIs, and a user](/mulesoft/current/en-us/gateway/1.12/_images/ad-egress-deployment.png)

## Sidecar Deployment

In a sidecar deployment, each Flex Gateway deployment only protects the APIs exposed by its
protected service. A new Flex Gateway replica is added with each new protected service.

As the following diagram shows, traffic in a sidecar deployment passes through Flex Gateway to the
respective consumer API. The consumer application can belong to the same network as Flex Gateway or
an external network.

![In a sidecar deployment, Flex Gateway and the consumer application are in the same Kubernetes pod.](/mulesoft/current/en-us/gateway/1.12/_images/ad-sidecar-deployment.png)

## Routing Configuration Methods

There are different routing configuration methods dependent on what mode Flex Gateway is running in
or what technological stack Flex Gateway is deployed on.

How connections between Flex Gateway and services are configured is independent of the deployment
model.

### Control Plane

In control plane routing configuration, Flex Gateway and service connections are configured in a
remote control plane. For Flex Gateway, the control plane is Anypoint Platfrom. Control plane
configuration is only available in Flex Gateway Connected Mode.

### Custom Resource Definitions (CRDs)

In custom resource definitions (CRDs) routing configuration, Flex Gateway and service connections
are configured in custom resource yaml files.

For Flex Gateway, the CRDs are `APIinstance`, `Service`, `PolicyBinding`, and `Configuration` and
are defined in the
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

In Flex Gateway CRDs define connections in Local Mode but are also necessary for some connections in
Connected Mode.

### Kubernetes Ingress Resource

Flex Gateways running in Local Mode and deployed on Kubernetes can use Kubernetes `Ingress`
resources to define connection routing. When routing is defined via `Ingress` resources, Flex
Gateway acts as an Ingress Controller. `Ingress` resources are only avaliable in Kubernetes Local
Mode.

You can use `Ingress` resources and CRDs simultaneously.

For more information about how to configure Flex Gateway as an Ingress Controller, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class).

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc-overview)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.12/flex-architecture-shared-storage)

<!-- document id=d4c1d099a87a6c6a02d18573ff05642832cd04aed4894bbf2dbee43af414b646 url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-basic-deployments.md -->

---
product: Omni Gateway
version: 1.9
---

# Flex Gateway Deployment Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports multiple deployment models, which apply to both Connected Mode and Local Mode:

- [Standalone deployment](#standalone-deployment)

- [Ingress deployment](#ingress-deployment)

- [Egress deployment](#egress-deployment)

- [Sidecar deployment](#sidecar-deployment)

You can extend the deployment models in this overview to all technological stacks that have the
appropriate network controls applied. For more information about routing configuration modes, see
[Routing Configuration Methods](#routing-configuration-methods).

All the following diagrams show Flex Gateway running in Connected Mode. For Flex Gateway running in
Local Mode, the only difference is that Anypoint Platform would not be present in the deployment
model. This does not affect how information flows between Flex Gateway and the upstream and
downstream services.

## Standalone Deployment

In a standalone deployment, Flex Gateway acts as a standalone service that protects one or more
integration API flows by managing internal traffic.

As the following diagram shows, all traffic is inside an organization-owned network. The traffic
passes through Flex Gateway before reaching the consumer APIs.

![In a standalone deployment, Flex Gateway and the consumer applications are in the same network.](/mulesoft/current/en-us/gateway/1.9/_images/ad-standalone-deployment.png)

## Ingress Deployment

Similar to standalone deployment, in an ingress deployment, Flex Gateway acts as a standalone
service that protects one or more integration API flows. However, in an ingress deployment, Flex
Gateway manages external traffic entering the internal network. Ingress deployment is the most
common deployment model.

Flex Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all external traffic passes through Flex Gateway before reaching the
consumer APIs. Flex Gateway is typically deployed behind a load balancer, and the consumer
application does not belong to the same network as Flex Gateway or the APIs.

![In an ingress deployment, Flex Gateway and the consumer applications are in different networks.](/mulesoft/current/en-us/gateway/1.9/_images/ad-ingress-deployment.png)

> [!NOTE] Ingress deployment is not the same as a Kubernetes Ingress controller or Ingress
> `Resource`. For more information about routing configuration, see
> [Routing Configuration Methods](#routing-configuration-methods).

## Egress Deployment

An egress deployment is the opposite deployment model of an ingress deployment. Flex Gateway still
acts as a standalone service that protects one or more integration API flows. However, in an egress
deployment, Flex Gateway manages internal traffic exiting the internal network, for example, API
requests to non-organization-owned APIs.

Flex Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all internal traffic from the consumer application passes through
Flex Gateway before reaching the external APIs.

![A diagram of Anypoint Platform depicting the flow of data between the platform, a Flex Gateway, APIs, and a user](/mulesoft/current/en-us/gateway/1.9/_images/ad-egress-deployment.png)

## Sidecar Deployment

In a sidecar deployment, each Flex Gateway deployment only protects the APIs exposed by its
protected service. A new Flex Gateway replica is added with each new protected service.

As the following diagram shows, traffic in a sidecar deployment passes through Flex Gateway to the
respective consumer API. The consumer application can belong to the same network as Flex Gateway or
an external network.

![In a sidecar deployment, Flex Gateway and the consumer application are in the same Kubernetes pod.](/mulesoft/current/en-us/gateway/1.9/_images/ad-sidecar-deployment.png)

## Routing Configuration Methods

There are different routing configuration methods dependent on what mode Flex Gateway is running in
or what technological stack Flex Gateway is deployed on.

How connections between Flex Gateway and services are configured is independent of the deployment
model.

### Control Plane

In control plane routing configuration, Flex Gateway and service connections are configured in a
remote control plane. For Flex Gateway, the control plane is Anypoint Platfrom. Control plane
configuration is only available in Flex Gateway Connected Mode.

### Custom Resource Definitions (CRDs)

In custom resource definitions (CRDs) routing configuration, Flex Gateway and service connections
are configured in custom resource yaml files.

For Flex Gateway, the CRDs are `APIinstance`, `Service`, `PolicyBinding`, and `Configuration` and
are defined in the
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

In Flex Gateway CRDs define connections in Local Mode but are also necessary for some connections in
Connected Mode.

### Kubernetes Ingress Resource

Flex Gateways running in Local Mode and deployed on Kubernetes can use Kubernetes `Ingress`
resources to define connection routing. When routing is defined via `Ingress` resources, Flex
Gateway acts as an Ingress Controller. `Ingress` resources are only avaliable in Kubernetes Local
Mode.

You can use `Ingress` resources and CRDs simultaneously.

For more information about how to configure Flex Gateway as an Ingress Controller, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class).

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc-overview)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.9/flex-architecture-shared-storage)

<!-- document id=3f92ae6bfc32849a0a504de866d156865f53af3767f0d67943c4d4ad9bb8cfba url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-multi-region.md -->

---
product: Omni Gateway
version: 1.9
---

# Flex Gateway Multiple Region Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Install Flex Gateway in multiple regions to reduce latency and ensure live failover. You can
configure most implementations with either multiple Flex Gateways or multiple Flex Replicas.
Depending on which you choose, there are different considerations for Redis Shared-Storage,
policies, and logging. To learn more about Flex Replicas, see [Flex Replicas](https://docs.mulesoft.com/gateway/1.9/#replicas).

All the following diagrams show Flex Gateway running in Connected Mode. For Flex Gateway running in
Local Mode, the only difference is that Anypoint Platform isn’t present in the deployment model.
This doesn’t affect how information flows between Flex Gateway and the upstream and downstream
services.

The implementation diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

## Implementation 1: High Availability with the Same APIs in Two Separate Regions

Implementation 1 provides high availability for non-region-specific traffic. The DNS service is
configured for active-active failover, meaning each region services traffic at all times.

### Implementation 1A: Cross-Regional Flex Gateway

In this implementation:

- A single Flex Gateway has Flex Replicas distributed across multiple regions.

- Flex Gateway is registered once in Anypoint Platform and deployed across multiple regions and
  availability zones.

- Logs and metrics for each Flex Gateway are consolidated in Anypoint Platform.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- APIs deployed to the Gateway are available in all regions and availability zones.

- API configurations, including upstream services and policies are the same for all regions.
  Upstream services must be region-agnostic, meaning either the DNS is local or it lacks any
  reference to the region.

- The Redis cluster must be replicated across regions or Redis shared storage can’t be used. Redis
  replication is required when traffic isn’t region-specific.

- The only cross-regional traffic is Redis synchronization.

In the following diagram, Flex Replicas in different regions and availability zones have distinct
Kubernetes deployments:

![A detailed view of implementation 1A, which contains the necessary services to support high availability in for Flex Replicas deployed in different regions](/mulesoft/current/en-us/gateway/1.9/_images/high-availability-1a.png)

### Implementation 1B: Region-Specific Flex Gateway

In this implementation:

- Each region has a distinct Flex Gateway with all resources as independent entities.

- A separate Flex Gateway is registered for each region.

- Each region-specific API instance has distinct metrics, alerts, and logs in Anypoint Platform.

- Policies are region specific even if the configuration is similar across regions.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- API deployments are specific to each Flex Gateway. For each API a region supports, you must deploy
  an API instance to the region’s Flex Gateway.

- API Groups can share contracts (access requests) across regions. An API Group might not be
  required for your configuration.

- Redis shared storage does not require synchronization.

- There is no cross-regional traffic.

In the following diagram, all APIs are duplicated and don’t require identical configurations:

![A detailed view of implementation 1B, which contains the necessary services to support high availability for region-specific Flex Gateways](/mulesoft/current/en-us/gateway/1.9/_images/high-availability-1b.png)

## Implementation 2: Disaster Recovery for APIs

This implementation is similar to
[Implementation 1A: Cross-Regional Flex Gateway](#implementation-1a). However, the DNS service is
active-passive, so the standby region only receives traffic if the primary region becomes unhealthy.
This implementation is less complex to configure than implementation 1A.

Redis synchronization is not required if a cache loss during failover is acceptable.

In the following diagram, Flex Replicas in different availability zones have distinct Kubernetes
deployments. Region B provides high availability but receives traffic only if region A is unhealthy:

![A detailed view of implementation 2, which contains the necessary services to enable disaster recovery for APIs on Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/high-availability-2.png)

## Implementation 3: Direct Traffic to the Closest Region

In both [Implementation 3A: Direct Traffic to APIs With the Same Policies](#implementation-3a) and
[Implementation 3B: Direct Traffic to APIs With the Different Policies](#implementation-3b), Flex
Gateway directs traffic to the most convenient region to reduce latency. Choose which implementation
according to your policy requirements.

### Implementation 3A: Direct Traffic to APIs With the Same Policies

This implementation is similar to
[Implementation 1A: Cross-Regional Flex Gateway](#implementation-1a) and has the same
considerations. However, Redis replication is not required because requests are sent to specific
regions. Configure high availability or disaster recovery zones in each region to ensure API
availability:

![A detailed view of implementation 3A, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/1.9/_images/high-availability-3a.png)

### Implementation 3B: Direct Traffic to APIs With the Different Policies

This implementation is similar to
[Implementation 1B: Region-Specific Flex Gateway](#implementation-1b) and has the same
considerations. Deploy region-specific gateways and apply the necessary policies to the different
APIs. Configure high availability or disaster recovery zones in each region to ensure API
availability:

![A detailed view of implementation 3B, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/1.9/_images/high-availability-3b.png)

> [!NOTE] To apply SLA rate limiting across all regions, the rate limits must be the same for all
> regions. Use API groups to consolidate the contracts.

<!-- document id=ecd0637c67237f835b550b72325d2e4f14a826ece5e68ecd65439a415fbc3658 url=/mulesoft/current/en-us/gateway/1.12/index.md -->

---
product: Omni Gateway
version: 1.12
---

# Flex Gateway Overview

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway is an Envoy-based, ultrafast lightweight API gateway designed to manage and
secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD workflows, Flex
Gateway delivers the performance required for the most demanding applications and microservices
while providing enterprise security and manageability across any environment.

The following video provides a quick overview of Flex Gateway:

![](https://play.vidyard.com/3LncCho6hfvbLMKbg1AM28.jpg)

## Flex Gateway Architecture

Flex Gateway comprises two components that work in tandem:

- [Control plane](#control_plane)

- [Runtime](#runtime)

The following graphic diagrams the relationship between these components:

![A flowchart that illustrates the deployment and management of APIs](/mulesoft/current/en-us/gateway/1.12/_images/gateway-concepts-control-plane-diagram.png)

### Control plane

The control plane is a MuleSoft-hosted platform that centralizes management and observability,
enabling you to:

- Build APIs.

- Add policies.

- Deploy APIs into the runtime.

- Monitor APIs in Anypoint API Manager.

- Configure the runtime in Anypoint Runtime Manager.

### Runtime

The gateway runtime receives commands from the control plane and routes and protects the backend
APIs. Built with security in mind, Flex Gateway secures communications between the runtime and the
control plane through mTLS and HTTPs.

## Scaling

A single Flex Gateway can support up to 1,000 backend APIs. For high availability, it is best to
deploy multiple gateways running in parallel. Deploying multiple gateways increases gateway
performance and robustness, and is recommended for high-performance applications that must scale.

## Supported Protocols

Flex Gateway supports the following protocols:

- HTTP

- SOAP

- gRPC

- OAS3 REST API instances

- Model Context Protocol (MCP)

- Agent2Agent (A2A)

## Deployment Types

You can deploy Flex Gateway as a Managed or Self-Managed Flex Gateway. Managed Flex Gateway provides
a fully managed option on CloudHub 2.0 or Runtime Fabric, and Self-Managed Flex Gateway provides
more options and control.

- [Managed Flex Gateway](#managed)

- [Self-Managed Flex Gateway](#self_managed)

### Managed Flex Gateway

Managed Flex Gateway is a fully hosted version of Flex Gateway on CloudHub 2.0 or Runtime Fabric,
hosted and managed on the Anypoint Platform by MuleSoft. Managed Flex Gateway provides high
availability, autoscaling, less operational overhead, and regular automatic patches and upgrades. It
is designed to simplify API gateway operation through point-and-click setup, and monitoring, and
MuleSoft handles the maintenance and infrastructure.

In Managed Flex Gateway, each runtime unit is called a gateway instance.

### Self-Managed Flex Gateway

Self-Managed Flex Gateway is a distributed runtime entity that you can install in any cloud data
center or, for testing purposes, on your local laptop. Self-Managed Flex Gateway requires you to
manage the underlying infrastructure. Various installation options are available for the
Self-Managed Flex Gateway, including Docker containers, as a sidecar to a backend application in a
Docker container, as a Kubernetes Deployment, or on various Linux environments.

In Self-Managed Flex Gateway, each runtime unit is called a replica. For high availability, it is
best to deploy Self-Managed Flex Gateway as a cluster with multiple replicas running in parallel.
Using clusters increases gateway performance and robustness, and is recommended for high-performance
applications that must scale.

Self-Managed Flex Gateway includes a Fluent Bit implementation, which enables log output to local
files, or to aggregators such as New Relic, Sumo Logic, and Splunk. You can also configure external
REDIS storage for use with distributed rate limiting and caching. Gateway replicas utilize this
storage as a temporary workspace for rate limit coordination, which is pivotal in preserving
customer service level agreements.

Self-Managed Flex Gateway can be installed in either of these two modes:

- [Self-Managed Flex Gateway in Connected Mode](#connected_mode)

- [Self-Managed Flex Gateway in Local Mode](#local_mode)

### Self-Managed Flex Gateway in Connected Mode

In Connected Mode, the gateway is fully connected to the MuleSoft control plane. This connection
allows for centralized management, observability, and security. Anypoint API Manager enables full
API lifecycle management and policy configuration. Anypoint Runtime Manager enables you to deploy
and configure your gateway.

Choose Connected Mode for a UI-based experience to deploy policies, and for managing and monitoring
the gateway.

### Self-Managed Flex Gateway in Local Mode

You can also configure and manage a standalone gateway that is mostly disconnected from the control
plane. Choose Local Mode for this experience.

> [!NOTE] Flex Gateway deployed in Local Mode only connects to the control plane for registration
> and logging usage metrics.

In Local Mode, you manage all configuration and policy applications with locally stored declarative
configuration files.

Use Local Mode to build CI/CD pipelines for application deployments.

### Summary of Differences

The following table summarizes the differences between Connected Mode and Local Mode.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th></th><th>Connected Mode</th><th>Local Mode</th></tr></thead><tbody><tr><td><div><div><p><strong>Use Case</strong></p></div></div></td><td><div><div><p>Centralize management, observability, and security. Flex Gateway connects to the control plane.</p></div></div></td><td><div><div><p>Operate independently of the control plane in a mostly disconnected manner. Manage with locally stored declarative configuration files. Build CI/CD pipelines.</p></div></div></td></tr><tr><td><div><div><p><strong>Policy Application</strong></p></div></div></td><td><div><div><p>Via API Manager</p></div></div></td><td><div><div><p>Via local declarative configuration files</p></div></div></td></tr><tr><td><div><div><p><strong>Air-Gapped?</strong></p></div></div></td><td><div><div><p>No. Flex Gateway is connected to the control plane.</p></div></div></td><td><div><div><p>No. Flex Gateway is managed locally but only connected to the control plane for registration and usage metrics.</p></div></div></td></tr></tbody></table>

## Deployment and Installation Options

### Managed Deployment Options

You can deploy Managed Flex Gateway on CloudHub 2.0 and Runtime Fabric using Runtime Manager. For
details see [Deploy a Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-managed-set-up).

### Self-Managed Installation Options

You can install Self-Managed Flex Gateway in a variety of ways:

- A standalone runtime in a Docker container deployed on Heroku from Salesforce

  To learn more, see
  [Mastering API Integration: Salesforce, Heroku, and MuleSoft Anypoint Flex Gateway](https://blog.heroku.com/mastering-api-integration-salesforce-heroku-mulesoft-anypoint-flex-gateway).

- A standalone runtime in a Docker container

- A sidecar to a backend application in a Docker container, thereby protecting a single backend
  application

- A Kubernetes `Deployment` for high-availability, high-performance use cases

- An OpenShift on IBM Power `Deployment` for high-availability, high-performance use cases

- A standalone single runtime or replica on various Linux environments, including:

  - Amazon Linux 2023

  - CentOS 8

  - Debian Bookworm

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - Ubuntu Jammy

A standalone gateway is good for protecting a limited number of APIs with low transaction volume.
However, for other scenarios, or if high availability and reliability are critical, consider using
an Ingress controller in Kubernetes.

## Version Retirement Dates

For information about Flex Gateway version retirement dates, refer to
[MuleSoft Product Versioning and Back Support Policy](https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Shared Responsibility

The successful operation of Flex Gateway is a responsibility shared between you and MuleSoft.

### MuleSoft Responsibility

MuleSoft is responsible for:

- Providing and supporting Flex Gateway (including the agent, Envoy package, and Fluent Bit package)

- Providing and supporting a base Helm chart for the installation of Flex Gateway in a Kubernetes
  cluster

- Providing and supporting an online Docker image registry

- Providing and supporting an online package repository for installation on Linux

### Your Responsibility

When running on any target, you are responsible for:

- Maintaining connectivity to the Anypoint Control Plane

- Not running third-party software that interferes with normal Flex Gateway operation, such as
  antivirus, DPI, or application security systems

When running in Kubernetes, you are responsible for:

- Adapting the base Helm chart for your specific needs

- Managing the Kubernetes `Deployment`, including:

  - External load balancing

  - Customizations to `Ingress` resources

  - Log forwarding

  - Monitoring

  - Network ports, NAT gateways, and proxies

  - Container runtime and networking

  - Provisioning and management of the Kubernetes environment, which requires:

    - Your IT team to provision and manage the infrastructure

    - Your network team to configure allowed ports and proxy settings

    - Your security team to verify compliance and obtain security certificates

See [Viewing Usage Reports](https://docs.mulesoft.com/general/usage-reports) for information about your monthly Flex
Gateway usage.

## Next Steps

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

<!-- document id=1792c42600ee1a3b8a53c638b11cb947c234743d5ce717b98cfdec7ffadc8498 url=/mulesoft/current/en-us/gateway/1.9/index.md -->

---
product: Omni Gateway
version: 1.9
---

# Flex Gateway Overview

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway is an Envoy-based, ultrafast lightweight API gateway designed to manage and
secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD workflows, Flex
Gateway delivers the performance required for the most demanding applications and microservices
while providing enterprise security and manageability across any environment.

The following video provides a quick overview of Flex Gateway:

![](https://play.vidyard.com/3LncCho6hfvbLMKbg1AM28.jpg)

## Flex Gateway Architecture

Flex Gateway comprises two components that work in tandem:

- [Control plane](#control_plane)

- [Runtime](#runtime)

The following graphic diagrams the relationship between these components:

![A flowchart that illustrates the deployment and management of APIs](/mulesoft/current/en-us/gateway/1.9/_images/gateway-concepts-control-plane-diagram.png)

### Control plane

The control plane is a MuleSoft-hosted platform that centralizes management and observability,
enabling you to:

- Build APIs.

- Add policies.

- Deploy APIs into the runtime.

- Monitor APIs in Anypoint API Manager.

- Configure the runtime in Anypoint Runtime Manager.

### Runtime

The gateway runtime receives commands from the control plane and routes and protects the backend
APIs. Built with security in mind, Flex Gateway secures communications between the runtime and the
control plane through mTLS and HTTPs.

## Scaling

A single Flex Gateway can support up to 1,000 backend APIs. For high availability, it is best to
deploy multiple gateways running in parallel. Deploying multiple gateways increases gateway
performance and robustness, and is recommended for high-performance applications that must scale.

## API Instances

Flex Gateway supports HTTP and REST API instances.

Flex Gateway does not natively support SOAP APIs and does not provide any schema validation for XML.
However, you can publish an HTTP API instance to secure any API that uses HTTP protocol.

To publish a SOAP API, refer to [Troubleshooting SOAP APIs](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-soap-apis).

## Deployment Types

You can deploy Flex Gateway as a Managed or Self-Managed Flex Gateway. Managed Flex Gateway on
CloudHub 2.0 provides a fully managed option, and Self-Managed Flex Gateway provides more options
and control.

- [Managed Flex Gateway](#managed)

- [Self-Managed Flex Gateway](#self_managed)

### Managed Flex Gateway

Managed Flex Gateway is a fully hosted version of Flex Gateway on CloudHub 2.0, hosted and managed
on the Anypoint Platform by MuleSoft. Managed Flex Gateway provides high availability, autoscaling,
less operational overhead, and regular automatic patches and upgrades. It is designed to simplify
API gateway operation through point-and-click setup, and monitoring, and MuleSoft handles the
maintenance and infrastructure.

In Managed Flex Gateway, each runtime unit is called a gateway instance.

### Self-Managed Flex Gateway

Self-Managed Flex Gateway is a distributed runtime entity that you can install in any cloud data
center or, for testing purposes, on your local laptop. Self-Managed Flex Gateway requires you to
manage the underlying infrastructure. Various installation options are available for the
Self-Managed Flex Gateway, including Docker containers, as a sidecar to a backend application in a
Docker container, as a Kubernetes Deployment, or on various Linux environments.

In Self-Managed Flex Gateway, each runtime unit is called a replica. For high availability, it is
best to deploy Self-Managed Flex Gateway as a cluster with multiple replicas running in parallel.
Using clusters increases gateway performance and robustness, and is recommended for high-performance
applications that must scale.

Self-Managed Flex Gateway includes a Fluent Bit implementation, which enables log output to local
files, or to aggregators such as New Relic, Sumo Logic, and Splunk. You can also configure external
REDIS storage for use with distributed rate limiting and caching. Gateway replicas utilize this
storage as a temporary workspace for rate limit coordination, which is pivotal in preserving
customer service level agreements.

Self-Managed Flex Gateway can be installed in either of these two modes:

- [Self-Managed Flex Gateway in Connected Mode](#connected_mode)

- [Self-Managed Flex Gateway in Local Mode](#local_mode)

### Self-Managed Flex Gateway in Connected Mode

In Connected Mode, the gateway is fully connected to the MuleSoft control plane. This connection
allows for centralized management, observability, and security. Anypoint API Manager enables full
API lifecycle management and policy configuration. Anypoint Runtime Manager enables you to deploy
and configure your gateway.

Choose Connected Mode for a UI-based experience to deploy policies, and for managing and monitoring
the gateway.

### Self-Managed Flex Gateway in Local Mode

You can also configure and manage a standalone gateway that is mostly disconnected from the control
plane. Choose Local Mode for this experience.

> [!NOTE] Flex Gateway deployed in Local Mode only connects to the control plane for registration
> and logging usage metrics.

In Local Mode, you manage all configuration and policy applications with locally stored declarative
configuration files.

Use Local Mode to build CI/CD pipelines for application deployments.

### Summary of Differences

The following table summarizes the differences between Connected Mode and Local Mode.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th></th><th>Connected Mode</th><th>Local Mode</th></tr></thead><tbody><tr><td><div><div><p><strong>Use Case</strong></p></div></div></td><td><div><div><p>Centralize management, observability, and security. Flex Gateway connects to the control plane.</p></div></div></td><td><div><div><p>Operate independently of the control plane in a mostly disconnected manner. Manage with locally stored declarative configuration files. Build CI/CD pipelines.</p></div></div></td></tr><tr><td><div><div><p><strong>Policy Application</strong></p></div></div></td><td><div><div><p>Via API Manager</p></div></div></td><td><div><div><p>Via local declarative configuration files</p></div></div></td></tr><tr><td><div><div><p><strong>Air-Gapped?</strong></p></div></div></td><td><div><div><p>No. Flex Gateway is connected to the control plane.</p></div></div></td><td><div><div><p>No. Flex Gateway is managed locally but only connected to the control plane for registration and usage metrics.</p></div></div></td></tr></tbody></table>

## Deployment and Installation Options

### Managed Deployment Options

You can deploy Managed Flex Gateway on CloudHub 2.0 using Runtime Manager. For details see
[Deploy a Managed Flex Gateway to CloudHub 2.0](https://docs.mulesoft.com/gateway/1.9/flex-gateway-managed-set-up).

### Self-Managed Installation Options

You can install Self-Managed Flex Gateway in a variety of ways:

- A standalone runtime in a Docker container deployed on Heroku from Salesforce

  To learn more, see
  [Mastering API Integration: Salesforce, Heroku, and MuleSoft Anypoint Flex Gateway](https://www.heroku.com/blog/mastering-api-integration-salesforce-heroku-mulesoft-anypoint-flex-gateway/).

- A standalone runtime in a Docker container

- A sidecar to a backend application in a Docker container, thereby protecting a single backend
  application

- A Kubernetes `Deployment` for high-availability, high-performance use cases

- An OpenShift on IBM Power `Deployment` for high-availability, high-performance use cases

- A standalone single runtime or replica on various Linux environments, including:

  - Amazon Linux 2023

  - CentOS 8

  - Debian (Bullseye, Bookworm)

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - SUSE Linux Enterprise (SLES 15 SP3)

  - SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

  - Ubuntu (Focal, Jammy)

A standalone gateway is good for protecting a limited number of APIs with low transaction volume.
However, for other scenarios, or if high availability and reliability are critical, consider using
an Ingress controller in Kubernetes.

## Version Retirement Dates

For information about Flex Gateway version retirement dates, refer to
[MuleSoft Product Versioning and Back Support Policy](https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Shared Responsibility

The successful operation of Flex Gateway is a responsibility shared between you and MuleSoft.

### MuleSoft Responsibility

MuleSoft is responsible for:

- Providing and supporting Flex Gateway (including the agent, Envoy package, and Fluent Bit package)

- Providing and supporting a base Helm chart for the installation of Flex Gateway in a Kubernetes
  cluster

- Providing and supporting an online Docker image registry

- Providing and supporting an online package repository for installation on Linux

### Your Responsibility

When running on any target, you are responsible for:

- Maintaining connectivity to the Anypoint Control Plane

- Not running third-party software that interferes with normal Flex Gateway operation, such as
  antivirus, DPI, or application security systems

When running in Kubernetes, you are responsible for:

- Adapting the base Helm chart for your specific needs

- Managing the Kubernetes `Deployment`, including:

  - External load balancing

  - Customizations to `Ingress` resources

  - Log forwarding

  - Monitoring

  - Network ports, NAT gateways, and proxies

  - Container runtime and networking

  - Provisioning and management of the Kubernetes environment, which requires:

    - Your IT team to provision and manage the infrastructure

    - Your network team to configure allowed ports and proxy settings

    - Your security team to verify compliance and obtain security certificates

See [Viewing Usage Reports](https://docs.mulesoft.com/general/usage-reports) for information about your monthly Flex
Gateway usage.

## Next Steps

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

<!-- document id=9542ea4276bfae2cdc14e4d644eb79a71358aecc205017d9b927a94c9e6d1058 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-overview.md -->

---
product: Omni Gateway
version: 1.12
---

# Flex Gateway Reference Architecture

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following architecture diagrams explain Flex Gateway concepts and deployments:

- [Flex Gateway Deployment Models](https://docs.mulesoft.com/gateway/1.12/flex-architecture-basic-deployments)

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc-overview)

  - [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1)

  - [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2)

  - [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3)

  - [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4)

- [High Availability and Disaster Recovery](https://docs.mulesoft.com/gateway/1.12/flex-architecture-dr-ha-overview)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.12/flex-architecture-shared-storage)

<!-- document id=ff545d07327ac8fa40d00a01dbb3512f10c14310b3c2cc9f2855c1ac17e3ffc4 url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-overview.md -->

---
product: Omni Gateway
version: 1.9
---

# Flex Gateway Reference Architecture

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following architecture diagrams explain Flex Gateway concepts and deployments:

- [Flex Gateway Deployment Models](https://docs.mulesoft.com/gateway/1.9/flex-architecture-basic-deployments)

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc-overview)

  - [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1)

  - [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2)

  - [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3)

  - [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4)

- [Flex Gateway Multiple Region Deployments](https://docs.mulesoft.com/gateway/1.9/flex-architecture-multi-region)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.9/flex-architecture-shared-storage)

<!-- document id=7affb193856b3c45602343e73631555945bc87bf5cd486f7523ef32c18ab2e9b url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-version-lifecycle.md -->

---
product: Omni Gateway
version: 1.12
---

# Flex Gateway Version Lifecycle

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Starting with Flex Gateway 1.9, MuleSoft introduces two new release channels, Edge and Long-term
Support (LTS). These release channels are available for both Managed and Self-Managed Flex Gateway.

## Edge and LTS Releases for Flex Gateway

Consider the information in this table to determine which release channel best suits your
requirements.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Channel Type</th><th>Release Cadence</th><th>Differentiators</th><th>Support Coverage</th></tr></thead><tbody><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>Three times per year</p></div><div><ul><li><p>May</p></li><li><p>August</p></li><li><p>November</p></li></ul></div></div></td><td><div><div><p>Includes new features more often and has a shorter support period for each release.</p></div></div></td><td><div><div><p>Flex Gateway 1.9 and later</p></div><div><ul><li><p>Five months Standard Support</p></li><li><p>Three months Extended Support</p></li></ul></div><div><p>Flex Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr><tr><td><div><div><p><strong>LTS</strong></p></div></div></td><td><div><div><p>Once a year</p></div><div><ul><li><p>February</p></li></ul></div></div></td><td><div><div><p>Bundles new features in an annual release and has a longer support period for each release.</p></div></div></td><td><div><div><p>Flex Gateway 1.9 and later</p></div><div><ul><li><p>Eighteen months Standard Support</p></li><li><p>Six months Extended Support</p></li></ul></div><div><p>Flex Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr></tbody></table>

> [!NOTE] Release dates are subject to change due to product needs.

For detailed information and support timeframes for Flex Gateway 1.8 and earlier, see the
[MuleSoft Support Policy](https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Flex Gateway Version Support

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Flex Gateway Version</th><th>Release Date</th><th>End of Standard Support</th><th>End of Extended Support</th></tr></thead><tbody><tr><td><div><div><p>1.12.0 LTS</p></div></div></td><td><div><div><p>February 25, 2026</p></div></div></td><td><div><div><p>August 25, 2027</p></div></div></td><td><div><div><p>February 25, 2028</p></div></div></td></tr><tr><td><div><div><p>1.11.0 Edge</p></div></div></td><td><div><div><p>October 15, 2025</p></div></div></td><td><div><div><p>March 15, 2026</p></div></div></td><td><div><div><p>June 15, 2026</p></div></div></td></tr><tr><td><div><div><p>1.10.0 Edge</p></div></div></td><td><div><div><p>June 27, 2025</p></div></div></td><td><div><div><p>November 27, 2025</p></div></div></td><td><div><div><p>February 27, 2026</p></div></div></td></tr><tr><td><div><div><p>1.9.0 LTS</p></div></div></td><td><div><div><p>March 18, 2025</p></div></div></td><td><div><div><p>September 18, 2026</p></div></div></td><td><div><div><p>March 18, 2027</p></div></div></td></tr></tbody></table>

## Deployment Models and Lifecycle Management

Flex Gateway lifecycle management varies depending on the release channel and the type of gateway.
Managed Flex Gateway instances are auto-upgraded regularly, and any available patches are applied
once a month. Self-managed gateways are never patched or upgraded automatically.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Managed Gateway</th><th>Self-Managed Gateway</th></tr></thead><tbody><tr><td><div><div><p>Auto-upgrade</p></div></div></td><td><div><div><p>Managed Gateways are auto-upgraded to the latest minor version within their respective channels (Edge or LTS).</p></div><div><ul><li><p>Edge: Three times per year</p></li><li><p>LTS: Once a year</p></li></ul></div></div></td><td><div><div><p>No auto-upgrade capabilities</p></div></div></td></tr><tr><td><div><div><p>Patches</p></div></div></td><td><div><div><p>Monthly auto-patching</p></div></div></td><td><div><div><p>Available for Flex Gateway versions that are within the support period for their respective channels (Edge or LTS).</p></div></div></td></tr><tr><td><div><div><p>Self-upgrade</p></div></div></td><td><div><div><p>You can manually upgrade to the latest version that matches your release channel (Edge or LTS) before the scheduled automatic upgrade.</p></div></div></td><td><div><div><p>Always available</p></div></div></td></tr><tr><td><div><div><p>Rollback</p></div></div></td><td><div><div><p>You can revert to the previous version if it’s still within the release channel support period.</p></div></div></td><td><div><div><p>Available to the previously used version</p></div></div></td></tr><tr><td><div><div><p>Restart</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Keep running</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Supportability</p></div></div></td><td><div><div><p>Standard Support (auto-upgrade ensures that managed gateways are always on the latest Edge or LTS version).</p></div></div></td><td><div><div><p>Until End of Extended Support. See the <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a> for more information.</p></div></div></td></tr></tbody></table>

For information on patching, upgrading, rolling back, or deleting a gateway, see
[Maintaining a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-maintain).

<!-- document id=acd8bacb19120baccfe6e2f093a5a275813ad86c49d18cae3ec8876cd550602a url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-version-lifecycle.md -->

---
product: Omni Gateway
version: 1.9
---

# Flex Gateway Version Lifecycle

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Starting with Flex Gateway 1.9, MuleSoft introduces two new release channels, Edge and Long-term
Support (LTS). These release channels are available for both Managed and Self-Managed Flex Gateway.

## Edge and LTS Releases for Flex Gateway

Consider the information in this table to determine which release channel best suits your
requirements.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Channel Type</th><th>Release Cadence</th><th>Differentiators</th><th>Support Coverage</th></tr></thead><tbody><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>Three times per year</p></div><div><ul><li><p>March</p></li><li><p>July</p></li><li><p>November</p></li></ul></div></div></td><td><div><div><p>Includes new features more often and has a shorter support period for each release.</p></div></div></td><td><div><div><p>Flex Gateway 1.9 and later</p></div><div><ul><li><p>Four months Standard Support</p></li><li><p>Four months Extended Support</p></li></ul></div><div><p>Flex Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr><tr><td><div><div><p><strong>LTS</strong></p></div></div></td><td><div><div><p>Once a year</p></div><div><ul><li><p>March</p></li></ul></div></div></td><td><div><div><p>Bundles new features in an annual release and has a longer support period for each release.</p></div></div></td><td><div><div><p>Flex Gateway 1.9 and later</p></div><div><ul><li><p>Twelve months Standard Support</p></li><li><p>Twelve months Extended Support</p></li></ul></div><div><p>Flex Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr></tbody></table>

For detailed information and support timeframes for Flex Gateway 1.8 and earlier, see the
[MuleSoft Support Policy](https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Deployment Models and Lifecycle Management

Flex Gateway lifecycle management varies depending on the release channel and the type of gateway.
Managed Flex Gateway instances are auto-upgraded regularly, and any available patches are applied
once a month. Self-managed gateways are never patched or upgraded automatically.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Managed Gateway</th><th>Self-Managed Gateway</th></tr></thead><tbody><tr><td><div><div><p>Auto-upgrade</p></div></div></td><td><div><div><p>Managed Gateways are auto-upgraded to the latest minor version within their respective channels (Edge or LTS).</p></div><div><ul><li><p>Edge: Three times per year</p></li><li><p>LTS: Once a year</p></li></ul></div></div></td><td><div><div><p>No auto-upgrade capabilities</p></div></div></td></tr><tr><td><div><div><p>Patches</p></div></div></td><td><div><div><p>Monthly auto-patching</p></div></div></td><td><div><div><p>Available for Flex Gateway versions that are within the support period for their respective channels (Edge or LTS).</p></div></div></td></tr><tr><td><div><div><p>Self-upgrade</p></div></div></td><td><div><div><p>You can manually upgrade to the latest version that matches your release channel (Edge or LTS) before the scheduled automatic upgrade.</p></div></div></td><td><div><div><p>Always available</p></div></div></td></tr><tr><td><div><div><p>Rollback</p></div></div></td><td><div><div><p>You can revert to the previous version if it’s still within the release channel support period.</p></div></div></td><td><div><div><p>Available to the previously used version</p></div></div></td></tr><tr><td><div><div><p>Restart</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Keep running</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Supportability</p></div></div></td><td><div><div><p>Standard Support (auto-upgrade ensures that managed gateways are always on the latest Edge or LTS version).</p></div></div></td><td><div><div><p>Until End of Extended Support. See the <a href="https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a> for more information.</p></div></div></td></tr></tbody></table>

For information on patching, upgrading, rolling back, or deleting a gateway, see
[Maintaining a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-maintain).

<!-- document id=2c236111d088481434351c58753c11c5e500c4eb766e4dce1c051db3cb100462 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-getting-started-overview.md -->

---
product: Omni Gateway
version: 1.12
---

# Getting Started with Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway provides the following guides to quickly get started with Anypoint Flex Gateway. The
tutorial describes how to deploy a Flex Gateway and publish a simple API that is secured with a
basic authentication policy. See the guide for you desired Flex Gateway deployment type:

- [Getting Started with Managed Flex Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/1.12/flex-gateway-managed-getting-started) -
  Deploy a Anypoint Platform hosted Managed Flex Gateway to CloudHub 2.0.

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started) - Deploy a
  Self-Managed Flex Gateway to a Docker container on your local infrastructure.

- [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-getting-started) -
  Deploy a Self-Managed Flex Gateway to a Kubernetes pod on your local infrastructure.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

<!-- document id=fdb13cb3763524be991f2b9fd21d612873eae40fa0c04b0e98451f19420d77d5 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-getting-started-overview.md -->

---
product: Omni Gateway
version: 1.9
---

# Getting Started with Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway provides the following guides to quickly get started with Anypoint Flex Gateway. The
tutorial describes how to deploy a Flex Gateway and publish a simple API that is secured with a
basic authentication policy. See the guide for you desired Flex Gateway deployment type:

- [Getting Started with Managed Flex Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/1.9/flex-gateway-managed-getting-started) -
  Deploy a Anypoint Platform hosted Managed Flex Gateway to CloudHub 2.0.

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started) - Deploy a
  Self-Managed Flex Gateway to a Docker container on your local infrastructure.

- [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-getting-started) -
  Deploy a Self-Managed Flex Gateway to a Kubernetes pod on your local infrastructure.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up)

<!-- document id=b098911c1cd30979d0744c4e49a7748d784a4ccf59c4ce0a5ae92e8334f029b3 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-managed-getting-started.md -->

---
product: Omni Gateway
version: 1.12
---

# Getting Started with Managed Flex Gateway on CloudHub 2.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Anypoint Managed Flex Gateway on CloudHub 2.0. Create and deploy a Managed Flex
Gateway, publish an API, and secure the API with a basic authentication policy.

## Before You Begin

Before getting started with Flex Gateway, complete these steps:

- Review the [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites) and verify that
  you have the necessary Managed Flex Gateway permissions.

- Create a private space in CloudHub 2.0 or verify that you can access an existing private space. To
  create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Deploy a Managed Flex Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Click **Flex Gateways** in the sidebar.

3.  Click **Managed Flex Gateway**.

4.  Click **Add Managed Flex Gateway**.

5.  Enter a **Gateway name**.

6.  Select a your private space as your **Deployment target**.

7.  Click **Advanced options**.

8.  Copy and save the Managed Flex Gateway public endpoint for later testing. This is the HTTP or
    HTTPs URL that appears in the **Public endpoint** UI block, for example,
    `[https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/](https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/)`.

9.  Click **Save & deploy**.

    The UI returns to the dashboard of your new Managed Flex Gateway.

10. Wait until your gateway’s **Status** is **Running**.

## Publish a Simple API

1.  From your Managed Gateway’s dashboard, click **Add API instance**.

2.  From the **Add API** page, select **Flex Gateway** as your runtime.

3.  Select your deployed Managed Flex Gateway in the **Select a gateway** section.

4.  Click **Next**.

5.  Click **Create New API**.

6.  Specify an API name and select **HTTP API** as the asset type.

7.  Click **Next**.

8.  Don’t configure any downstream options.

9.  Click **Next**.

10. From the **Upstream** page:

    1.  Enter this URL in the **Upstream URL** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

11. Click **Next**.

12. Click **Save & Deploy**.

    The UI takes you to the **API Summary** page of the newly created API instance.

    All HTTP requests made to the public endpoint are now proxied to the `jsonplaceholder` service.

13. To test the API instance, replace the public endpoint placeholder and run this command in a new
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  From the **API Summary** page, select **Policies** from the side navigation panel.

2.  In the **Policies** page, click **Add inbound policy**.

3.  Select the **Basic Authentication - Simple** policy.

4.  Click **Next**.

5.  For **User Name**, enter `user`.

6.  For **User Password**, enter `password`.

7.  Click **Apply**.

8.  To test the API Instance _without_ authentication, replace the public endpoint placeholder and
    run this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

9.  To test the API Instance _with_ authentication, replace the public endpoint placeholder and run
    this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

<!-- document id=9b6a98eb805c3b0875d27dcb22579fd22524fbd72b667880ab0db7a5b6941cf9 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-managed-getting-started.md -->

---
product: Omni Gateway
version: 1.9
---

# Getting Started with Managed Flex Gateway on CloudHub 2.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Anypoint Managed Flex Gateway on CloudHub 2.0. Create and deploy a Managed Flex
Gateway, publish an API, and secure the API with a basic authentication policy.

## Before You Begin

Before getting started with Flex Gateway, complete these steps:

- Review the [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites) and verify that
  you have the necessary Managed Flex Gateway permissions.

- Create a private space in CloudHub 2.0 or verify that you can access an existing private space. To
  create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Deploy a Managed Flex Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Click **Flex Gateways** in the sidebar.

3.  Click **Managed Flex Gateway**.

4.  Click **Add Managed Flex Gateway**.

5.  Enter a **Gateway name**.

6.  Select a your private space as your **Deployment target**.

7.  Click **Advanced options**.

8.  Copy and save the Managed Flex Gateway public endpoint for later testing. This is the HTTP or
    HTTPs URL that appears in the **Public endpoint** UI block, for example,
    `[https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/](https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/)`.

9.  Click **Save & deploy**.

    The UI returns to the dashboard of your new Managed Flex Gateway.

10. Wait until your gateway’s **Status** is **Running**.

## Publish a Simple API

1.  From your Managed Gateway’s dashboard, click **Add API instance**.

2.  From the **Add API** page, select **Flex Gateway** as your runtime.

3.  Select your deployed Managed Flex Gateway in the **Select a gateway** section.

4.  Click **Next**.

5.  Click **Create New API**.

6.  Specify an API name and select **HTTP API** as the asset type.

7.  Click **Next**.

8.  Don’t configure any downstream options.

9.  Click **Next**.

10. From the **Upstream** page:

    1.  Enter this URL in the **Upstream URL** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

11. Click **Next**.

12. Click **Save & Deploy**.

    The UI takes you to the **API Summary** page of the newly created API instance.

    All HTTP requests made to the public endpoint are now proxied to the `jsonplaceholder` service.

13. To test the API instance, replace the public endpoint placeholder and run this command in a new
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  From the **API Summary** page, select **Policies** from the side navigation panel.

2.  In the **Policies** page, click **Add inbound policy**.

3.  Select the **Basic Authentication - Simple** policy.

4.  Click **Next**.

5.  For **User Name**, enter `user`.

6.  For **User Password**, enter `password`.

7.  Click **Apply**.

8.  To test the API Instance _without_ authentication, replace the public endpoint placeholder and
    run this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

9.  To test the API Instance _with_ authentication, replace the public endpoint placeholder and run
    this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up)

<!-- document id=dcb54179ed03260be67a4fd6416a910c2b242d4656179e4b62d0f970073424cd url=/mulesoft/current/en-us/gateway/1.13/gateway-managed-getting-started.md -->

---
product: Omni Gateway
version: 1.13
---

# Getting Started with Managed Omni Gateway on CloudHub 2.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Anypoint Managed Omni Gateway on CloudHub 2.0. Create and deploy a Managed Omni
Gateway, publish an API, and secure the API with a basic authentication policy.

## Before You Begin

Before getting started with Omni Gateway, complete these steps:

- Review the [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites) and verify that you
  have the necessary Managed Omni Gateway permissions.

- Create a private space in CloudHub 2.0 or verify that you can access an existing private space. To
  create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Deploy a Managed Omni Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Click **Omni Gateways** in the sidebar.

3.  Click **Managed Omni Gateway**.

4.  Click **Add Managed Omni Gateway**.

5.  Enter a **Gateway name**.

6.  Select a your private space as your **Deployment target**.

7.  Click **Advanced options**.

8.  Copy and save the Managed Omni Gateway public endpoint for later testing. This is the HTTP or
    HTTPs URL that appears in the **Public endpoint** UI block, for example,
    `[https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/](https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/)`.

9.  Click **Save & deploy**.

    The UI returns to the dashboard of your new Managed Omni Gateway.

10. Wait until your gateway’s **Status** is **Running**.

## Publish a Simple API

1.  From your Managed Gateway’s dashboard, click **Add API instance**.

2.  From the **Add API** page, select **Omni Gateway** as your runtime.

3.  Select your deployed Managed Omni Gateway in the **Select a gateway** section.

4.  Click **Next**.

5.  Click **Create New API**.

6.  Specify an API name and select **HTTP API** as the asset type.

7.  Click **Next**.

8.  Don’t configure any downstream options.

9.  Click **Next**.

10. From the **Upstream** page:

    1.  Enter this URL in the **Upstream URL** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

11. Click **Next**.

12. Click **Save & Deploy**.

    The UI takes you to the **API Summary** page of the newly created API instance.

    All HTTP requests made to the public endpoint are now proxied to the `jsonplaceholder` service.

13. To test the API instance, replace the public endpoint placeholder and run this command in a new
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  From the **API Summary** page, select **Policies** from the side navigation panel.

2.  In the **Policies** page, click **Add inbound policy**.

3.  Select the **Basic Authentication - Simple** policy.

4.  Click **Next**.

5.  For **User Name**, enter `user`.

6.  For **User Password**, enter `password`.

7.  Click **Apply**.

8.  To test the API Instance _without_ authentication, replace the public endpoint placeholder and
    run this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

9.  To test the API Instance _with_ authentication, replace the public endpoint placeholder and run
    this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

<!-- document id=bd2517193375ffe5750021305c58be8e0bedd65f4f5e352c96d64b78bbc804d1 url=/mulesoft/current/en-us/gateway/latest/gateway-managed-getting-started.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Getting Started with Managed Omni Gateway on CloudHub 2.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Anypoint Managed Omni Gateway on CloudHub 2.0. Create and deploy a Managed Omni
Gateway, publish an API, and secure the API with a basic authentication policy.

## Before You Begin

Before getting started with Omni Gateway, complete these steps:

- Review the [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites) and verify that you
  have the necessary Managed Omni Gateway permissions.

- Create a private space in CloudHub 2.0 or verify that you can access an existing private space. To
  create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Deploy a Managed Omni Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Click **Omni Gateways** in the sidebar.

3.  Click **Managed Omni Gateway**.

4.  Click **Add Managed Omni Gateway**.

5.  Enter a **Gateway name**.

6.  Select a your private space as your **Deployment target**.

7.  Click **Advanced options**.

8.  Copy and save the Managed Omni Gateway public endpoint for later testing. This is the HTTP or
    HTTPs URL that appears in the **Public endpoint** UI block, for example,
    `[https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/](https://my-gateway-abc123.edf456.us-east1.anypoint.mulesoft.com/)`.

9.  Click **Save & deploy**.

    The UI returns to the dashboard of your new Managed Omni Gateway.

10. Wait until your gateway’s **Status** is **Running**.

## Publish a Simple API

1.  From your Managed Gateway’s dashboard, click **Add API instance**.

2.  From the **Add API** page, select **Omni Gateway** as your runtime.

3.  Select your deployed Managed Omni Gateway in the **Select a gateway** section.

4.  Click **Next**.

5.  Click **Create New API**.

6.  Specify an API name and select **HTTP API** as the asset type.

7.  Click **Next**.

8.  Don’t configure any downstream options.

9.  Click **Next**.

10. From the **Upstream** page:

    1.  Enter this URL in the **Upstream URL** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

11. Click **Next**.

12. Click **Save & Deploy**.

    The UI takes you to the **API Summary** page of the newly created API instance.

    All HTTP requests made to the public endpoint are now proxied to the `jsonplaceholder` service.

13. To test the API instance, replace the public endpoint placeholder and run this command in a new
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  From the **API Summary** page, select **Policies** from the side navigation panel.

2.  In the **Policies** page, click **Add inbound policy**.

3.  Select the **Basic Authentication - Simple** policy.

4.  Click **Next**.

5.  For **User Name**, enter `user`.

6.  For **User Password**, enter `password`.

7.  Click **Apply**.

8.  To test the API Instance _without_ authentication, replace the public endpoint placeholder and
    run this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

9.  To test the API Instance _with_ authentication, replace the public endpoint placeholder and run
    this command in the terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET '<publicEndpoint>' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

<!-- document id=83f3e9a26e065fb92d3991c34cb26c1f134cf00811919d1001ee8019241c55c4 url=/mulesoft/current/en-us/gateway/1.13/gateway-getting-started-overview.md -->

---
product: Omni Gateway
version: 1.13
---

# Getting Started with Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides the following guides to quickly get started with Omni Gateway. The tutorial
describes how to deploy an Omni Gateway and publish a simple API that is secured with a basic
authentication policy. See the guide for you desired Omni Gateway deployment type:

- [Getting Started with Managed Omni Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/1.13/gateway-managed-getting-started) -
  Deploy a Anypoint Platform hosted Managed Omni Gateway to CloudHub 2.0.

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started) - Deploy a Self-Managed
  Omni Gateway to a Docker container on your local infrastructure.

- [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-k8-getting-started) -
  Deploy a Self-Managed Omni Gateway to a Kubernetes pod on your local infrastructure.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

<!-- document id=f746627623cf52b9e04c5954c54e76171b913f4a916a25129a44df011ee28106 url=/mulesoft/current/en-us/gateway/latest/gateway-getting-started-overview.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Getting Started with Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway provides the following guides to quickly get started with Omni Gateway. The tutorial
describes how to deploy an Omni Gateway and publish a simple API that is secured with a basic
authentication policy. See the guide for you desired Omni Gateway deployment type:

- [Getting Started with Managed Omni Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/latest/gateway-managed-getting-started) -
  Deploy a Anypoint Platform hosted Managed Omni Gateway to CloudHub 2.0.

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started) - Deploy a Self-Managed
  Omni Gateway to a Docker container on your local infrastructure.

- [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-k8-getting-started) -
  Deploy a Self-Managed Omni Gateway to a Kubernetes pod on your local infrastructure.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

<!-- document id=6bb5a370f101abb1db4894cb75c9bb2a41712deb24714076e849cb8ece8b22df url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-getting-started.md -->

---
product: Omni Gateway
version: 1.12
---

# Getting Started with Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The goal of this tutorial is to quickly get started with Anypoint Flex Gateway. Using Docker, the
tutorial describes how to install, register, and run Flex Gateway in Connected Mode. Additionally,
the tutorial describes how to publish an API that is secured with a basic authentication policy.

## Before You Begin

Before getting started with Flex Gateway, ensure that you have:

- A username and password for your Anypoint Platform organization. If you don’t have Anypoint
  Platform yet, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Linux machine with an x86 processor. M1 and M2 processors are not supported.

  Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

  - Amazon Linux 2023

  - CentOS 8

  - Debian Bookworm

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - Ubuntu Jammy

- A Docker installation. See [Docker Desktop](https://www.docker.com/products/docker-desktop/) for
  an example.

## Download Flex Gateway

To download the Flex Gateway Docker image, run the following command in a terminal window:

```ssh
docker pull mulesoft/flex-gateway:latest
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

## Register Flex Gateway

1.  Create a new directory by running:

    ```ssh
    mkdir flex-registration
    ```

2.  Navigate to the new directory by running:

    ```ssh
    cd flex-registration
    ```

3.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

4.  Select **Runtime Manager**.

5.  Click **Flex Gateways** in the side navigation panel.

6.  Click **Self-managed Flex Gateways**.

7.  Click **Add Gateway**.

8.  Select **Docker**.

9.  Copy the code block in the **Register your gateway** section. The code block contains your
    unique organization ID and token.

    The following screenshot of the **Add a Flex Gateway** page highlights the code block to copy:

    ![A code block with a command to register a Flex Gateway with Anypoint Platform](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-add-gateway.png)

10. Run the copied code block in your terminal window, making sure to first replace `<gateway-name>`
    with a name, such as `my-gw`.

    > [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

11. In Runtime Manager, select **Flex Gateways** from the side navigation panel.

    Your registered Flex Gateway now appears in the list of gateways.

## Run Flex Gateway

To run Flex Gateway, run the following in a terminal window:

```ssh
docker run --rm \
  -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
  -p 8081:8081 \
  mulesoft/flex-gateway
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

A new Flex Gateway instance is now running in your terminal window.

> [!NOTE] The Flex Gateway instance will continue running in the terminal window until the process
> is stopped, or until the window is closed.

## Publish a Simple API

1.  Select **API Manager** from the Anypoint Platform menu.

2.  Click **Add API** > **Add new API**.

3.  From the **Add API** page, select **Flex Gateway** as your runtime.

4.  Select your registered gateway in the **Select a gateway** section.

5.  Click **Next**.

6.  Click **Create New API**.

7.  Specify an API name and select **HTTP API** as the asset type.

8.  Click **Next**.

9.  From the **Endpoint** page, enter the following in the **Implementation URI** field:

    ```none
    https://jsonplaceholder.typicode.com/
    ```

10. Enter `8081` in the **Port** field.

11. Click **Next**.

12. Click **Save & Deploy**.

    Inside the gateway instance Docker container, all HTTP requests made to `localhost` on port
    `8081` are now proxied to the `jsonplaceholder` service.

13. To test the API Instance, run the following command in a new terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  While still in **API Manager**, select **API Instances** from the side navigation panel.

2.  Select the name of the API created in the previous section.

3.  Select **Policies** from the side navigation panel.

4.  In the **Policies** page, click **Add policy**.

    The following screenshot of the **Policies** page highlights the specified options:

    ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-add-policy.png)

5.  Select the **Basic Authentication - Simple** policy.

6.  Click **Next**.

7.  For **User Name**, enter `user`.

8.  For **User Password**, enter `password`.

9.  Click **Apply**.

    The following screenshot of the **Configure Basic Authentication - Simple policy** page
    highlights the specified options:

    ![Configure Basic Authentication Policy page with User Password field selected](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-config-basic-auth.png)

10. To test the API Instance _without_ authentication, run the following `curl` command in the
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

11. To test the API Instance _with_ authentication, run the following command in the terminal
    window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

<!-- document id=e585507fc3096e3c9eaddad49a87037b673bd980318e88ef8394b0c0295d42fc url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-getting-started.md -->

---
product: Omni Gateway
version: 1.9
---

# Getting Started with Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The goal of this tutorial is to quickly get started with Anypoint Flex Gateway. Using Docker, the
tutorial describes how to install, register, and run Flex Gateway in Connected Mode. Additionally,
the tutorial describes how to publish an API that is secured with a basic authentication policy.

## Before You Begin

Before getting started with Flex Gateway, ensure that you have:

- A username and password for your Anypoint Platform organization. If you don’t have Anypoint
  Platform yet, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Linux machine with an x86 processor. M1 and M2 processors are not supported.

  Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

  - Amazon Linux 2023

  - CentOS 8

  - Debian (Bullseye, Bookworm)

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - SUSE Linux Enterprise (SLES 15 SP3)

  - SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

  - Ubuntu (Focal, Jammy)

- A Docker installation. See [Docker Desktop](https://www.docker.com/products/docker-desktop/) for
  an example.

## Download Flex Gateway

To download the Flex Gateway Docker image, run the following command in a terminal window:

```ssh
docker pull mulesoft/flex-gateway:latest
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

## Register Flex Gateway

1.  Create a new directory by running:

    ```ssh
    mkdir flex-registration
    ```

2.  Navigate to the new directory by running:

    ```ssh
    cd flex-registration
    ```

3.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

4.  Select **Runtime Manager**.

5.  Click **Flex Gateways** in the side navigation panel.

6.  Click **Self-managed Flex Gateways**.

7.  Click **Add Gateway**.

8.  Select **Docker**.

9.  Copy the code block in the **Register your gateway** section. The code block contains your
    unique organization ID and token.

    The following screenshot of the **Add a Flex Gateway** page highlights the code block to copy:

    ![A code block with a command to register a Flex Gateway with Anypoint Platform](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-add-gateway.png)

10. Run the copied code block in your terminal window, making sure to first replace `<gateway-name>`
    with a name, such as `my-gw`.

    > [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

11. In Runtime Manager, select **Flex Gateways** from the side navigation panel.

    Your registered Flex Gateway now appears in the list of gateways.

## Run Flex Gateway

To run Flex Gateway, run the following in a terminal window:

```ssh
docker run --rm \
  -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
  -p 8081:8081 \
  mulesoft/flex-gateway
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

A new Flex Gateway instance is now running in your terminal window.

> [!NOTE] The Flex Gateway instance will continue running in the terminal window until the process
> is stopped, or until the window is closed.

## Publish a Simple API

1.  Select **API Manager** from the Anypoint Platform menu.

2.  Click **Add API**, followed by **Add new API**:

    ![Add new API page with Add new API selected](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-add-new-api.png)

3.  From the **Add API** page, select **Flex Gateway** as your runtime.

4.  Select your registered gateway in the **Select a gateway** section.

5.  Click **Next**.

    The following screenshot of the **Add API** page highlights the specified options:

    ![Add API page with Flex Gateway Runtime and my-gw gateway selected](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-select-gateway-for-api.png)

6.  Click **Create New API**.

7.  Specify an API name and select **HTTP API** as the asset type.

8.  Click **Next**.

9.  From the **Endpoint** page, enter the following in the **Implementation URI** field:

    ```none
    https://jsonplaceholder.typicode.com/
    ```

10. Enter `8081` in the **Port** field.

11. Click **Next**.

12. Click **Save & Deploy**.

    Inside the gateway instance Docker container, all HTTP requests made to `localhost` on port
    `8081` are now proxied to the `jsonplaceholder` service.

13. To test the API Instance, run the following command in a new terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  While still in **API Manager**, select **API Administration** from the side navigation panel.

2.  Select the name of the API created in the previous section.

3.  Select **Policies** from the side navigation panel.

4.  In the **Policies** page, click **Add policy**.

    The following screenshot of the **Policies** page highlights the specified options:

    ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-add-policy.png)

5.  Select the **Basic Authentication - Simple** policy.

6.  Click **Next**.

7.  For **User Name**, enter `user`.

8.  For **User Password**, enter `password`.

9.  Click **Apply**.

    The following screenshot of the **Configure Basic Authentication - Simple policy** page
    highlights the specified options:

    ![Configure Basic Authentication Policy page with User Password field selected](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-config-basic-auth.png)

10. To test the API Instance _without_ authentication, run the following `curl` command in the
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

11. To test the API Instance _with_ authentication, run the following command in the terminal
    window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up)

<!-- document id=775bec9d89679b213674992b7f5a87f0baf92c259789539e6ef59c5fe183d189 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-k8-getting-started.md -->

---
product: Omni Gateway
version: 1.12
---

# Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Anypoint Flex Gateway in a Kubernetes cluster or an OpenShift cluster, which is
based on Kubernetes. Set up a Flex Gateway deployment that connects to Anypoint Platform, and use
the deployment to route traffic to your API. This guide covers the following high-level tasks:

- Downloading, registering, and deploying Flex Gateway in
  [Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run-token#k8-token) with a token

- Creating a simple API in Anypoint API Manager that runs on your gateway

- Protecting the API with a basic authentication policy that you configure in API Manager

The Flex Gateway deployment process requires a working Kubernetes cluster that you create or that is
provisioned for you by a Kubernetes professional.

Setting up a Kubernetes cluster requires a level of skill and expertise that is _beyond the scope of
this guide to provide_. Cluster configuration in Kubernetes differs significantly by service
provider and platform. For cluster configuration questions, consult documentation from your
Kubernetes service provider or use the
[Kubernetes documentation](https://kubernetes.io/docs/setup/).

If you lack a Kubernetes cluster but want to try out Flex Gateway quickly, without creating a
cluster, see [Getting Started with Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started) (on Docker). That
guide uses Docker exclusively and does not require you to perform any cluster configuration.

## Before You Begin

Before starting the procedures in this guide, ensure that the following prerequisites are in place:

- A username and password for your Anypoint Platform organization. If you do not have an Anypoint
  Platform account, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Docker installation.

  Run `docker --version` from a terminal window to determine if this tool is installed. If you need
  to install Docker, try [Docker Desktop](https://www.docker.com/).

- A minimum Helm version of 3.0.0 is required.

  Run `helm version` from a terminal window to determine if this tool is installed and check the
  version. To install or upgrade, use the [Helm](https://helm.sh/) website.

- The Kubernetes `kubectl` command-line tool.

  Run `kubectl version --output=yaml` from a terminal window to determine if this tool is installed.
  If not, find `kubectl` among the installation tools available through the
  [Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/).

- The `curl` command-line tool.

  Run `curl --version` from a terminal window to determine if this tool is installed. If not, you
  can download it with a package manager for your machine.

## Cluster Requirements

The host for your Kubernetes cluster can be any
[supported Kubernetes provider](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites#software-requirements), including common
cloud-based services, such as Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service
(AKS), or Google Kubernetes Engine (GKE).

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

To complete the procedures in this guide, you must create a Kubernetes cluster or use an existing
one for your Flex Gateway deployment. In this guide, you use Helm to deploy Flex Gateway to a
Kubernetes cluster and connect it to Anypoint Platform.

The following minimum requirements apply to a small Kubernetes cluster used for demonstration
purposes in this guide and _do not apply to requirements of a production environment_:

- At least one node.

- Support for the creation of a `Service` resource of the `LoadBalancer` type.

  This requirement avoids deployment errors when you use this guide. However, it is possible to
  customize the `Service` type when deploying a gateway. Flex Gateway supports the following
  services: `ClusterIP`, `NodePort`, `LoadBalancer` (default), `ExternalName`. See the
  `service.type` key in the
  [Helm chart for Flex Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

- Compute resources needed for the deployment procedure are _very unlikely_ to exceed the following
  values (equivalent to the EKS t3.micro instance type):

  - vCPU: 2 vCPUs

  - Memory: 1 GiB

  - Network: Up to 5 Gigabit

  - Max ENI: 2

  - Max IPs: 4

To determine whether your cluster is ready for the [deployment procedure](#deploy-flex), review
[Check Your Cluster](#check-cluster) _before starting_ the deployment. The checks require you to run
a set of `kubectl` commands.

## Step 1: Download the Flex Gateway Image

Use Docker to download the Flex Gateway image from the Docker Hub registry.

This procedure is a prerequisite to registering the Flex Gateway with Anypoint Platform in
[Step 2: Register Flex Gateway](#register-flex). Registration is required during the gateway
deployment through Helm in [Step 4: Deploy and Connect Flex Gateway](#deploy-flex).

1.  Check that Docker is running by executing the following command in a terminal window:

    ```docker
    docker info
    ```

    If you receive an error after executing this command, see the information about
    [Docker troubleshooting](#docker-troubleshooting).

2.  Run the following command in a terminal window:

    ```docker
    docker pull mulesoft/flex-gateway:latest
    ```

    When successful, this command prints a message similar to the following one in your terminal
    window:

    latest: Pulling from mulesoft/flex-gateway Digest: sha256:e55555abcdefg1234567zxynwo33333fadjf
    Status: Image is up to date for mulesoft/flex-gateway:latest
    docker.io/mulesoft/flex-gateway:latest

    Use `sudo` if you encounter permission issues when running this command.

## Step 2: Register Flex Gateway

Register the Flex Gateway image from a terminal window using a temporary token generated by Anypoint
Runtime Manager. This procedure produces a local `registration.yaml` file that contains registration
properties for a named gateway. These properties are incorporated into a Helm chart in
[Step 4: Deploy and Connect Flex Gateway](#deploy-flex).

1.  From a terminal window, prepare a directory for a Flex Gateway registration file
    (`registration.yaml`).

    1.  Create a directory:

        ```mkdir
        mkdir flex-registration
        ```

    2.  Navigate to the new directory:

        ```cd
        cd flex-registration
        ```

2.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) and select **Runtime
    Manager**.

3.  From Runtime Manager, locate the procedure for registering Flex Gateway:

    1.  Click **Flex Gateways** in the side navigation panel.

    2.  Click **Self-managed Flex Gateways**.

    3.  Click **Add Managed Flex-Gateway**.

    4.  Select one of the following environments:

        - **Kubernetes**

        - **OpenShift**

    5.  In the page that opens, locate the command in the **Register your gateway** section.

        Kubernetes Example:

        ![Add registration code block from Add a Flex Gateway page](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-add-gateway-rtm.png)

        The highlighted command block includes your unique organization ID and a temporary token.

4.  In your terminal window, copy the command block from Runtime Manager to your
    `./flex-registration` directory.

    Notice that Runtime Manager provides the required organization and token values.

5.  Before running the command, replace `<gateway-name>` at the end of the command block with a
    _unique_ name for your gateway, such as `my-gateway`.

    The name that you provide for your gateway must be unique within the scope of your Anypoint
    Platform organization and environment. Completing this registration step is required once _and
    allowed no more than once_ per named gateway and organization.

6.  Run the edited command from your terminal window.

    When successful, the command produces a `registration.yaml` in your `./flex-registration`
    directory and displays the following message in your terminal window:

    Starting registration, please be patient. Registration completed, the configuration files were
    written in directory "/registration". For security, modify the file permissions to restrict
    production scenario access to the user running flex.

    Note that the message in the terminal window refers to a `/registration` directory that resides
    within the Docker container.

    Use `sudo` if you encounter file permission issues when running this command. If your token
    expires before you run the command, a `400 Bad Request` error occurs. In this case, you must
    refresh the Runtime Manager page to generate a new token and run the modified command that
    appears on the page.

## Step 3: Add a Repository for the Helm Chart

Add the Flex Gateway chart repository. Note that you can get more information about the properties
of the Helm chart for Flex Gateway in
[ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Add a Helm repository named `flex-gateway` for your Helm chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

## Step 4: Deploy and Connect Flex Gateway

Use Helm to deploy Flex Gateway to a node in your cluster and connect it to Anypoint Platform. After
deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint
Platform.

Before you begin:

Confirm that your Kubernetes cluster is available by following the steps in
[Check Your Cluster](#check-cluster). Review [Cluster Requirements](#kubernetes-cluster-reqs) if you
have not done so already. These prerequisites help avoid deployment errors.

After confirming that your Kubernetes cluster is ready, deploy and connect your gateway:

1.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and `ingress` release if they do not exist. The
    command syntax for the Helm repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

    If you receive an `UPGRADE FAILED` response, see
    [troubleshooting](#troubleshoot-helm-upgrade-failed) information about this issue.

2.  If you want to check the status of the Pod that runs your gateway, execute the following
    `kubectl` command:

    ```kubectl
    kubectl get pods -n gateway
    ```

    The output indicates whether the pod is running successfully in the `gateway` namespace:

    NAME READY STATUS RESTARTS AGE ingress-57bc75cb46-dmkdq 1/1 Running 0 35s

3.  Return to Runtime Manager:

    1.  Select **← Flex Gateways** from the side navigation panel of the **Add a Flex Gateway**
        page.

        ![Choose preferred operating system or environment](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-return-to-gateway-list.png)

    2.  Navigate to your registered gateway in the **Flex Gateways** page:

        ![A table of Flex Gateway details, such as name, ID, status, and last updated timestamp](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-my-gateway-rtm.png)

        You can use the search field in the page to narrow the list of gateways.

    3.  Make sure that the status of your gateway is **Running**.

        If the status is **Not Running**, it’s likely that the cluster configuration is incorrect or
        a network issue has occurred. Check [Troubleshooting](#troubleshooting-k8) for more
        information.

## Step 5: Publish and Deploy a Simple API to Flex Gateway

Create and deploy a simple API to your gateway in Anypoint API Manager:

1.  In Runtime Manager, click the **View APIs** menu option for your gateway to navigate to its
    **View APIs** page.

    ![View APIs menu item for Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-view-apis.png)

    Alternatively, you can navigate to API Manager from the Anypoint Platform menu.

2.  From the page that opens, click **Add API** (and if present, **Add new API**) to navigate to the
    **APIs / Add API** page in API Manager.

3.  From **APIs / Add API**, configure an API by working through the API configuration pages,
    starting with the **Runtime** configuration:

    ![Add API page with Flex Gateway Runtime and my-gateway selected](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-select-gateway-for-api.png)

    1.  From the **Runtime** configuration page, select **Flex Gateway** as your runtime.

    2.  Find and select your gateway in the **Select a gateway** area of the page.

        Use the search field to locate it, if necessary.

    3.  Click **Next** to open the **API** page.

4.  In the **API** configuration page associated with **APIs / Add API**, provide an API name and
    asset type:

    ![A form to select or create a new API](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-api-config-api.png)

    1.  Click **Create new API**.

        The remaining procedures walk you through steps for creating and testing a new HTTP API in
        Anypoint Exchange. Notice, however, that it is also possible to select an existing API from
        Exchange from this page. That process is described in the
        [Add a New API](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#add-a-new-api) in the API
        Manager documentation.

    2.  Provide an API name, such as **my-api**.

    3.  Select **HTTP API** as the asset type.

    4.  Click **Next** to open the **Endpoint** configuration page.

5.  In the **Endpoint** page associated with **APIs / Add API**, set up an endpoint for your API:

    ![A form for configuring endpoint settings](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-api-config-endpoint.png)

    1.  For the **Scheme**, use the default, **HTTP** setting.

        This guide focuses on a simple HTTP API. For HTTPS configuration details, see
        [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config).

    2.  Copy the following URI into the **Implementation URI** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

    3.  Type `80` in the **Port** field.

        The example in this guide uses HTTP port `80` instead of the API Manager default port,
        `8081`, because the created `Service` maps incoming port `80` to target port `80` on the
        Pod. See the `service.http.port` key in the
        [Helm chart for Flex Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

    4.  Click **Next** to open the **Review** page.

6.  In the **Review** page associated with **APIs / Add API**:

    1.  Review your API configuration.

    2.  If necessary, use **Edit** to revise any configurations.

    3.  When your configuration is correct, click **Save & Deploy**.

        Inside the gateway, all incoming HTTP requests on port `80` are proxied to the
        `jsonplaceholder` service.

7.  From a terminal window, test the API instance:

    1.  Get your external IP address and use it to check that your IP redirects to the
        **Implementation URI**:

        ```kubectl
        kubectl -n gateway get services
        ```

        The command returns a result that looks similar to this example:

        NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress LoadBalancer 10.100.145.109
        <123456.aws.com> 80:30524/TCP,443:31710/TCP 7d7h

        The `EXTERNAL-IP` value `<123456.aws.com>` is an example and not an actual value.

    2.  Run the following `curl` command, replacing `<your_external_ip>` with _your_ `EXTERNAL-IP`
        from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command executes a `GET` request to the API and prints a success code:

        200

        You can also run a simpler `curl` command to return an array of JSON objects from the
        service’s `/users` endpoint, for example:

        ```curl
        $ curl http://<your_external_ip>:80/users
        ```

## Step 6: Secure Your API Using the Basic Authentication Policy

Use API Manager to add a basic authentication policy to your API.

1.  In **API Manager**, select **API Instances** from the side navigation panel.

2.  Find and click the name of the API that you created in
    [Step 5: Publish and Deploy a Simple API to Flex Gateway](#create-api), such as **my-api**.

3.  Navigate to the **Policies** page for your API:

    1.  Select **Policies** from the side navigation panel.

    2.  On the **Policies** page, click **Add policy**.

        ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-add-policy.png)

4.  In the page that opens, find the **Security** policy called **Basic Authentication - Simple**
    policy.

    ![A form that empowers you to choose from a range of security policies](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-basic-auth.png)

    Be careful to avoid selecting the similarly named policy for LDAP.

5.  Click **Next**.

6.  Configure a Basic Authentication policy:

    ![Screenshot of 'Configure Basic Authentication - Simple policy' page](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-config-basic-auth.png)

    1.  For **User Name**, enter `user` instead of your real user name.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    2.  For **User Password**, enter `pw`.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    3.  Click **Apply**.

7.  Test the API instance:

    1.  Use `kubectl` to get your external IP address again so that you can use it in the next step:

        ```kubectl
        kubectl -n gateway get services
        ```

    2.  Run the following `curl` a command _without_ authentication parameters, replacing
        `<your_external_ip>` with the `EXTERNAL-IP` returned by preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command returns a `401` because the URI lacks authentication parameters:

        401

    3.  Run the following `curl` a command _with_ authentication parameters, replacing
        `<your_external_ip>` with your `EXTERNAL-IP` from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users' -u user:pw
        ```

        The command prints the resulting `200` status code, indicating success:

        200

        The `user` and `password` parameters (`user:pw`) must match the values you specified when
        you applied the policy. If you enter incorrect authentication parameters, the following
        error occurs:

        401

        To address the error, run the command with the correct authentication parameters, or return
        to the policy configuration page for your API in API Gateway, edit the policy configuration,
        and rerun the `curl` commands.

        ![Automated and API-level policy settings](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-config-basic-auth-edit-dialogue.png)

        The page for editing the credentials looks similar to this one:

        ![A form with fields to input a username and password](/mulesoft/current/en-us/gateway/1.12/_images/gateway-quickstart-k8-config-basic-auth-edit.png)

## Troubleshooting

If you encounter an error when running a command, check for troubleshooting information:

[Docker Command Issues](#docker-troubleshooting) | [Helm Command Issues](#helm-troubleshooting)

### Docker Command Issues

Troubleshoot errors returned by a `docker` command:

- [Docker Daemon Error](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

#### Docker Daemon Error

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

#### Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add a Flex Gateway**
  page for Kubernetes and rerun the registration command.

### Helm Command Issues

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

#### Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Flex Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See [Register Flex Gateway](#register-flex)
for an example of the registration command.

#### Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

#### Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Flex Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

#### Failed to Install CRD

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

## Check Your Cluster

Before deploying Flex Gateway to your Kubernetes cluster in
[Step 4: Deploy and Connect Flex Gateway](#deploy-flex), ensure that your cluster is ready. Use
`kubectl` to list and select (use) a cluster and to get a list of nodes that the cluster uses. If
any steps in this section fail, the deployment process is likely to produce errors.

To prevent potential timeout and connectivity errors when running procedures in this guide, your
cluster must meet the [Cluster Requirements](#kubernetes-cluster-reqs).

1.  Run `kubectl config get-contexts` to list the clusters, for example:

    ```kubectl
    kubectl config get-contexts
    ```

    This command is particularly helpful if you have multiple Kubernetes clusters. You can use the
    command to get the name of the correct cluster. For example, assume that you have a variety of
    clusters (`my-cluster`, `my-aks`, `my-gke`, `my-eks`). The command prints a list of your
    clusters.

    The following _example_ shows a list of clusters produced by the command:

    CURRENT NAME CLUSTER AUTHINFO NAMESPACE my-cluster my-cluster my-cluster1 my-aks my-aks my-aks
    my-gke my-gke my-gke my-eks my-eks my-eks

    If your cluster is not listed and you are using a custom cluster context file on your machine to
    connect to your cluster, you might need to add its path to a `KUBECONFIG` environment variable
    that points to that file. By default, `kubectl` searches for a file named `config` in the
    `$HOME/.kube` directory. That file lists each `context`, which provides properties such as the
    cluster name, user, and certificate authority data.

    You can check by running `echo $KUBECONFIG` from your terminal window, which prints a
    environment variable’s value, similar to this example:

    {KUBECONFIG}:/Users/me/.kube/config:/Users/me/.kube/additional-clusters/my-gke:/Users/me/.kube/additional-clusters/my-aks:/Users/me/.kube/additional-clusters/my-eks

    Adding the path to any additional cluster context files on your machine enables the
    `kubectl config get-contexts` command to list the cluster contexts and for you to use them.

    For more detail, see the
    [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
    about the `kubeconfig` file.

2.  Provide the name of a cluster into which you plan to deploy your gateway.

    The following example uses the cluster `my-eks`, identified in the cluster list example:

    kubectl config use-context my-eks

    The command switches to the selected cluster context and prints a message similar to this one:

    Switched to context "my-eks".

    If you receive an error that begins `error: no context exists with the name`, ensure you are
    using the `NAME` value of the cluster listed by `kubectl config get-contexts` and not the
    `CLUSTER` value.

3.  Check that your cluster has one or more nodes:

    ```kubectl
    kubectl get nodes
    ```

    The command returns a output similar to this example:

    NAME STATUS ROLES AGE VERSION ip-192-168-70-170 Ready <none> 17h v1.x.x ip-192-168-9-230 Ready
    <none> 17h v1.x.x

    Make sure that at least one node is in the `Ready` status.

4.  If your cluster is not ready, correct the cluster configuration.

    Alternatively, try the Docker-only guide,
    [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started), which does not
    use a Kubernetes cluster, and skip the next steps.

5.  If you have not started the Flex Gateway setup procedures yet, review
    [Cluster Requirements](#kubernetes-cluster-reqs) before proceeding to
    [Step 1: Download the Flex Gateway Image](#download-flex).

6.  If you have successfully completed all the procedures for downloading and registering your
    gateway with Docker and adding a repository for your Helm chart, and you are ready to begin the
    deployment procedure, go to [Step 4: Deploy and Connect Flex Gateway](#deploy-flex).

## Next Steps

Learn other ways to set up and configure Flex Gateway for a Kubernetes cluster, and review other
policy configuration options.

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

- [Configuring Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-configure)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management)

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory)

<!-- document id=95a9d7be2b7803fae339ea8c0ecc20724f88741c764aae0d4e48f562660262d7 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-k8-getting-started.md -->

---
product: Omni Gateway
version: 1.9
---

# Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Anypoint Flex Gateway in a Kubernetes cluster or an OpenShift cluster, which is
based on Kubernetes. Set up a Flex Gateway deployment that connects to Anypoint Platform, and use
the deployment to route traffic to your API. This guide covers the following high-level tasks:

- Downloading, registering, and deploying Flex Gateway in
  [Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run-token#k8-token) with a token

- Creating a simple API in Anypoint API Manager that runs on your gateway

- Protecting the API with a basic authentication policy that you configure in API Manager

The Flex Gateway deployment process requires a working Kubernetes cluster that you create or that is
provisioned for you by a Kubernetes professional.

Setting up a Kubernetes cluster requires a level of skill and expertise that is _beyond the scope of
this guide to provide_. Cluster configuration in Kubernetes differs significantly by service
provider and platform. For cluster configuration questions, consult documentation from your
Kubernetes service provider or use the
[Kubernetes documentation](https://kubernetes.io/docs/setup/).

If you lack a Kubernetes cluster but want to try out Flex Gateway quickly, without creating a
cluster, see [Getting Started with Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started) (on Docker). That
guide uses Docker exclusively and does not require you to perform any cluster configuration.

## Before You Begin

Before starting the procedures in this guide, ensure that the following prerequisites are in place:

- A username and password for your Anypoint Platform organization. If you do not have an Anypoint
  Platform account, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Docker installation.

  Run `docker --version` from a terminal window to determine if this tool is installed. If you need
  to install Docker, try [Docker Desktop](https://www.docker.com/).

- A minimum Helm version of 3.0.0 is required.

  Run `helm version` from a terminal window to determine if this tool is installed and check the
  version. To install or upgrade, use the [Helm](https://helm.sh/) website.

- The Kubernetes `kubectl` command-line tool.

  Run `kubectl version --output=yaml` from a terminal window to determine if this tool is installed.
  If not, find `kubectl` among the installation tools available through the
  [Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/).

- The `curl` command-line tool.

  Run `curl --version` from a terminal window to determine if this tool is installed. If not, you
  can download it with a package manager for your machine.

## Cluster Requirements

The host for your Kubernetes cluster can be any
[supported Kubernetes provider](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites#software-requirements), including common
cloud-based services, such as Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service
(AKS), or Google Kubernetes Engine (GKE).

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

To complete the procedures in this guide, you must create a Kubernetes cluster or use an existing
one for your Flex Gateway deployment. In this guide, you use Helm to deploy Flex Gateway to a
Kubernetes cluster and connect it to Anypoint Platform.

The following minimum requirements apply to a small Kubernetes cluster used for demonstration
purposes in this guide and _do not apply to requirements of a production environment_:

- At least one node.

- Support for the creation of a `Service` resource of the `LoadBalancer` type.

  This requirement avoids deployment errors when you use this guide. However, it is possible to
  customize the `Service` type when deploying a gateway. Flex Gateway supports the following
  services: `ClusterIP`, `NodePort`, `LoadBalancer` (default), `ExternalName`. See the
  `service.type` key in the
  [Helm chart for Flex Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

- Compute resources needed for the deployment procedure are _very unlikely_ to exceed the following
  values (equivalent to the EKS t3.micro instance type):

  - vCPU: 2 vCPUs

  - Memory: 1 GiB

  - Network: Up to 5 Gigabit

  - Max ENI: 2

  - Max IPs: 4

To determine whether your cluster is ready for the [deployment procedure](#deploy-flex), review
[Check Your Cluster](#check-cluster) _before starting_ the deployment. The checks require you to run
a set of `kubectl` commands.

## Step 1: Download the Flex Gateway Image

Use Docker to download the Flex Gateway image from the Docker Hub registry.

This procedure is a prerequisite to registering the Flex Gateway with Anypoint Platform in
[Step 2: Register Flex Gateway](#register-flex). Registration is required during the gateway
deployment through Helm in [Step 4: Deploy and Connect Flex Gateway](#deploy-flex).

1.  Check that Docker is running by executing the following command in a terminal window:

    ```docker
    docker info
    ```

    If you receive an error after executing this command, see the information about
    [Docker troubleshooting](#docker-troubleshooting).

2.  Run the following command in a terminal window:

    ```docker
    docker pull mulesoft/flex-gateway:latest
    ```

    When successful, this command prints a message similar to the following one in your terminal
    window:

    latest: Pulling from mulesoft/flex-gateway Digest: sha256:e55555abcdefg1234567zxynwo33333fadjf
    Status: Image is up to date for mulesoft/flex-gateway:latest
    docker.io/mulesoft/flex-gateway:latest

    Use `sudo` if you encounter permission issues when running this command.

## Step 2: Register Flex Gateway

Register the Flex Gateway image from a terminal window using a temporary token generated by Anypoint
Runtime Manager. This procedure produces a local `registration.yaml` file that contains registration
properties for a named gateway. These properties are incorporated into a Helm chart in
[Step 4: Deploy and Connect Flex Gateway](#deploy-flex).

1.  From a terminal window, prepare a directory for a Flex Gateway registration file
    (`registration.yaml`).

    1.  Create a directory:

        ```mkdir
        mkdir flex-registration
        ```

    2.  Navigate to the new directory:

        ```cd
        cd flex-registration
        ```

2.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) and select **Runtime
    Manager**.

3.  From Runtime Manager, locate the procedure for registering Flex Gateway:

    1.  Click **Flex Gateways** in the side navigation panel.

    2.  Click **Self-managed Flex Gateways**.

    3.  Click **Add Managed Flex-Gateway**.

    4.  Select one of the following environments:

        - **Kubernetes**

        - **OpenShift**

    5.  In the page that opens, locate the command in the **Register your gateway** section.

        Kubernetes Example:

        ![Add registration code block from Add a Flex Gateway page](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-add-gateway-rtm.png)

        The highlighted command block includes your unique organization ID and a temporary token.

4.  In your terminal window, copy the command block from Runtime Manager to your
    `./flex-registration` directory.

    Notice that Runtime Manager provides the required organization and token values.

5.  Before running the command, replace `<gateway-name>` at the end of the command block with a
    _unique_ name for your gateway, such as `my-gateway`.

    The name that you provide for your gateway must be unique within the scope of your Anypoint
    Platform organization and environment. Completing this registration step is required once _and
    allowed no more than once_ per named gateway and organization.

6.  Run the edited command from your terminal window.

    When successful, the command produces a `registration.yaml` in your `./flex-registration`
    directory and displays the following message in your terminal window:

    Starting registration, please be patient. Registration completed, the configuration files were
    written in directory "/registration". For security, modify the file permissions to restrict
    production scenario access to the user running flex.

    Note that the message in the terminal window refers to a `/registration` directory that resides
    within the Docker container.

    Use `sudo` if you encounter file permission issues when running this command. If your token
    expires before you run the command, a `400 Bad Request` error occurs. In this case, you must
    refresh the Runtime Manager page to generate a new token and run the modified command that
    appears on the page.

## Step 3: Add a Repository for the Helm Chart

Add the Flex Gateway chart repository. Note that you can get more information about the properties
of the Helm chart for Flex Gateway in
[ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Add a Helm repository named `flex-gateway` for your Helm chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

## Step 4: Deploy and Connect Flex Gateway

Use Helm to deploy Flex Gateway to a node in your cluster and connect it to Anypoint Platform. After
deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint
Platform.

Before you begin:

Confirm that your Kubernetes cluster is available by following the steps in
[Check Your Cluster](#check-cluster). Review [Cluster Requirements](#kubernetes-cluster-reqs) if you
have not done so already. These prerequisites help avoid deployment errors.

After confirming that your Kubernetes cluster is ready, deploy and connect your gateway:

1.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and `ingress` release if they do not exist. The
    command syntax for the Helm repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

    If you receive an `UPGRADE FAILED` response, see
    [troubleshooting](#troubleshoot-helm-upgrade-failed) information about this issue.

2.  If you want to check the status of the Pod that runs your gateway, execute the following
    `kubectl` command:

    ```kubectl
    kubectl get pods -n gateway
    ```

    The output indicates whether the pod is running successfully in the `gateway` namespace:

    NAME READY STATUS RESTARTS AGE ingress-57bc75cb46-dmkdq 1/1 Running 0 35s

3.  Return to Runtime Manager:

    1.  Select **← Flex Gateways** from the side navigation panel of the **Add a Flex Gateway**
        page.

        ![Choose preferred operating system or environment](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-return-to-gateway-list.png)

    2.  Navigate to your registered gateway in the **Flex Gateways** page:

        ![A table of Flex Gateway details, such as name, ID, status, and last updated timestamp](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-my-gateway-rtm.png)

        You can use the search field in the page to narrow the list of gateways.

    3.  Make sure that the status of your gateway is **Running**.

        If the status is **Not Running**, it’s likely that the cluster configuration is incorrect or
        a network issue has occurred. Check [Troubleshooting](#troubleshooting-k8) for more
        information.

## Step 5: Publish and Deploy a Simple API to Flex Gateway

Create and deploy a simple API to your gateway in Anypoint API Manager:

1.  In Runtime Manager, click the **View APIs** menu option for your gateway to navigate to its
    **View APIs** page.

    ![View APIs menu item for Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-view-apis.png)

    Alternatively, you can navigate to API Manager from the Anypoint Platform menu.

2.  From the page that opens, click **Add API** (and if present, **Add new API**) to navigate to the
    **APIs / Add API** page in API Manager.

3.  From **APIs / Add API**, configure an API by working through the API configuration pages,
    starting with the **Runtime** configuration:

    ![Add API page with Flex Gateway Runtime and my-gateway selected](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-select-gateway-for-api.png)

    1.  From the **Runtime** configuration page, select **Flex Gateway** as your runtime.

    2.  Find and select your gateway in the **Select a gateway** area of the page.

        Use the search field to locate it, if necessary.

    3.  Click **Next** to open the **API** page.

4.  In the **API** configuration page associated with **APIs / Add API**, provide an API name and
    asset type:

    ![A form to select or create a new API](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-api-config-api.png)

    1.  Click **Create new API**.

        The remaining procedures walk you through steps for creating and testing a new HTTP API in
        Anypoint Exchange. Notice, however, that it is also possible to select an existing API from
        Exchange from this page. That process is described in the
        [Add a New API](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#add-a-new-api) in the API
        Manager documentation.

    2.  Provide an API name, such as **my-api**.

    3.  Select **HTTP API** as the asset type.

    4.  Click **Next** to open the **Endpoint** configuration page.

5.  In the **Endpoint** page associated with **APIs / Add API**, set up an endpoint for your API:

    ![A form for configuring endpoint settings](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-api-config-endpoint.png)

    1.  For the **Scheme**, use the default, **HTTP** setting.

        This guide focuses on a simple HTTP API. For HTTPS configuration details, see
        [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config).

    2.  Copy the following URI into the **Implementation URI** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

    3.  Type `80` in the **Port** field.

        The example in this guide uses HTTP port `80` instead of the API Manager default port,
        `8081`, because the created `Service` maps incoming port `80` to target port `80` on the
        Pod. See the `service.http.port` key in the
        [Helm chart for Flex Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

    4.  Click **Next** to open the **Review** page.

6.  In the **Review** page associated with **APIs / Add API**:

    1.  Review your API configuration.

    2.  If necessary, use **Edit** to revise any configurations.

    3.  When your configuration is correct, click **Save & Deploy**.

        Inside the gateway, all incoming HTTP requests on port `80` are proxied to the
        `jsonplaceholder` service.

7.  From a terminal window, test the API instance:

    1.  Get your external IP address and use it to check that your IP redirects to the
        **Implementation URI**:

        ```kubectl
        kubectl -n gateway get services
        ```

        The command returns a result that looks similar to this example:

        NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress LoadBalancer 10.100.145.109
        <123456.aws.com> 80:30524/TCP,443:31710/TCP 7d7h

        The `EXTERNAL-IP` value `<123456.aws.com>` is an example and not an actual value.

    2.  Run the following `curl` command, replacing `<your_external_ip>` with _your_ `EXTERNAL-IP`
        from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command executes a `GET` request to the API and prints a success code:

        200

        You can also run a simpler `curl` command to return an array of JSON objects from the
        service’s `/users` endpoint, for example:

        ```curl
        $ curl http://<your_external_ip>:80/users
        ```

## Step 6: Secure Your API Using the Basic Authentication Policy

Use API Manager to add a basic authentication policy to your API.

1.  In **API Manager**, select **API Administration** from the side navigation panel.

2.  Find and click the name of the API that you created in
    [Step 5: Publish and Deploy a Simple API to Flex Gateway](#create-api), such as **my-api**.

3.  Navigate to the **Policies** page for your API:

    1.  Select **Policies** from the side navigation panel.

    2.  On the **Policies** page, click **Add policy**.

        ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-add-policy.png)

4.  In the page that opens, find the **Security** policy called **Basic Authentication - Simple**
    policy.

    ![A form that empowers you to choose from a range of security policies](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-basic-auth.png)

    Be careful to avoid selecting the similarly named policy for LDAP.

5.  Click **Next**.

6.  Configure a Basic Authentication policy:

    ![Screenshot of 'Configure Basic Authentication - Simple policy' page](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-config-basic-auth.png)

    1.  For **User Name**, enter `user` instead of your real user name.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    2.  For **User Password**, enter `pw`.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    3.  Click **Apply**.

7.  Test the API instance:

    1.  Use `kubectl` to get your external IP address again so that you can use it in the next step:

        ```kubectl
        kubectl -n gateway get services
        ```

    2.  Run the following `curl` a command _without_ authentication parameters, replacing
        `<your_external_ip>` with the `EXTERNAL-IP` returned by preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command returns a `401` because the URI lacks authentication parameters:

        401

    3.  Run the following `curl` a command _with_ authentication parameters, replacing
        `<your_external_ip>` with your `EXTERNAL-IP` from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users' -u user:pw
        ```

        The command prints the resulting `200` status code, indicating success:

        200

        The `user` and `password` parameters (`user:pw`) must match the values you specified when
        you applied the policy. If you enter incorrect authentication parameters, the following
        error occurs:

        401

        To address the error, run the command with the correct authentication parameters, or return
        to the policy configuration page for your API in API Gateway, edit the policy configuration,
        and rerun the `curl` commands.

        ![Automated and API-level policy settings](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-config-basic-auth-edit-dialogue.png)

        The page for editing the credentials looks similar to this one:

        ![A form with fields to input a username and password](/mulesoft/current/en-us/gateway/1.9/_images/gateway-quickstart-k8-config-basic-auth-edit.png)

## Troubleshooting

If you encounter an error when running a command, check for troubleshooting information:

[Docker Command Issues](#docker-troubleshooting) | [Helm Command Issues](#helm-troubleshooting)

### Docker Command Issues

Troubleshoot errors returned by a `docker` command:

- [Docker Daemon Error](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

#### Docker Daemon Error

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

#### Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add a Flex Gateway**
  page for Kubernetes and rerun the registration command.

### Helm Command Issues

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

#### Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Flex Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See [Register Flex Gateway](#register-flex)
for an example of the registration command.

#### Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

#### Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Flex Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

#### Failed to Install CRD

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

## Check Your Cluster

Before deploying Flex Gateway to your Kubernetes cluster in
[Step 4: Deploy and Connect Flex Gateway](#deploy-flex), ensure that your cluster is ready. Use
`kubectl` to list and select (use) a cluster and to get a list of nodes that the cluster uses. If
any steps in this section fail, the deployment process is likely to produce errors.

To prevent potential timeout and connectivity errors when running procedures in this guide, your
cluster must meet the [Cluster Requirements](#kubernetes-cluster-reqs).

1.  Run `kubectl config get-contexts` to list the clusters, for example:

    ```kubectl
    kubectl config get-contexts
    ```

    This command is particularly helpful if you have multiple Kubernetes clusters. You can use the
    command to get the name of the correct cluster. For example, assume that you have a variety of
    clusters (`my-cluster`, `my-aks`, `my-gke`, `my-eks`). The command prints a list of your
    clusters.

    The following _example_ shows a list of clusters produced by the command:

    CURRENT NAME CLUSTER AUTHINFO NAMESPACE my-cluster my-cluster my-cluster1 my-aks my-aks my-aks
    my-gke my-gke my-gke my-eks my-eks my-eks

    If your cluster is not listed and you are using a custom cluster context file on your machine to
    connect to your cluster, you might need to add its path to a `KUBECONFIG` environment variable
    that points to that file. By default, `kubectl` searches for a file named `config` in the
    `$HOME/.kube` directory. That file lists each `context`, which provides properties such as the
    cluster name, user, and certificate authority data.

    You can check by running `echo $KUBECONFIG` from your terminal window, which prints a
    environment variable’s value, similar to this example:

    {KUBECONFIG}:/Users/me/.kube/config:/Users/me/.kube/additional-clusters/my-gke:/Users/me/.kube/additional-clusters/my-aks:/Users/me/.kube/additional-clusters/my-eks

    Adding the path to any additional cluster context files on your machine enables the
    `kubectl config get-contexts` command to list the cluster contexts and for you to use them.

    For more detail, see the
    [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
    about the `kubeconfig` file.

2.  Provide the name of a cluster into which you plan to deploy your gateway.

    The following example uses the cluster `my-eks`, identified in the cluster list example:

    kubectl config use-context my-eks

    The command switches to the selected cluster context and prints a message similar to this one:

    Switched to context "my-eks".

    If you receive an error that begins `error: no context exists with the name`, ensure you are
    using the `NAME` value of the cluster listed by `kubectl config get-contexts` and not the
    `CLUSTER` value.

3.  Check that your cluster has one or more nodes:

    ```kubectl
    kubectl get nodes
    ```

    The command returns a output similar to this example:

    NAME STATUS ROLES AGE VERSION ip-192-168-70-170 Ready <none> 17h v1.x.x ip-192-168-9-230 Ready
    <none> 17h v1.x.x

    Make sure that at least one node is in the `Ready` status.

4.  If your cluster is not ready, correct the cluster configuration.

    Alternatively, try the Docker-only guide,
    [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started), which does not
    use a Kubernetes cluster, and skip the next steps.

5.  If you have not started the Flex Gateway setup procedures yet, review
    [Cluster Requirements](#kubernetes-cluster-reqs) before proceeding to
    [Step 1: Download the Flex Gateway Image](#download-flex).

6.  If you have successfully completed all the procedures for downloading and registering your
    gateway with Docker and adding a repository for your Helm chart, and you are ready to begin the
    deployment procedure, go to [Step 4: Deploy and Connect Flex Gateway](#deploy-flex).

## Next Steps

Learn other ways to set up and configure Flex Gateway for a Kubernetes cluster, and review other
policy configuration options.

- [Requirements and Limits for Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-review-prerequisites)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up)

- [Configuring Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-configure)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management)

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory)

<!-- document id=aac325b578b1acee9a5bafe5b1b37a9f29eeefd39f1a708753958e6539f71150 url=/mulesoft/current/en-us/gateway/1.13/gateway-getting-started.md -->

---
product: Omni Gateway
version: 1.13
---

# Getting Started with Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The goal of this tutorial is to quickly get started with Omni Gateway. Using Docker, the tutorial
describes how to install, register, and run Omni Gateway in Connected Mode. Additionally, the
tutorial describes how to publish an API that is secured with a basic authentication policy.

## Before You Begin

Before getting started with Omni Gateway, ensure that you have:

- A username and password for your Anypoint Platform organization. If you don’t have Anypoint
  Platform yet, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Linux machine with an x86 processor. M1 and M2 processors are not supported.

  Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

  - Amazon Linux 2023

  - CentOS 8

  - Debian Bookworm

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - Ubuntu Jammy

- A Docker installation. See [Docker Desktop](https://www.docker.com/products/docker-desktop/) for
  an example.

## Download Omni Gateway

To download the Omni Gateway Docker image, run the following command in a terminal window:

```ssh
docker pull mulesoft/flex-gateway:latest
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

## Register Omni Gateway

1.  Create a new directory by running:

    ```ssh
    mkdir flex-registration
    ```

2.  Navigate to the new directory by running:

    ```ssh
    cd flex-registration
    ```

3.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

4.  Select **Runtime Manager**.

5.  Click **Omni Gateways** in the side navigation panel.

6.  Click **Self-managed Omni Gateways**.

7.  Click **Add Gateway**.

8.  Select **Docker**.

9.  Copy the code block in the **Register your gateway** section. The code block contains your
    unique organization ID and token.

    The following screenshot of the **Add an Omni Gateway** page highlights the code block to copy:

    ![A code block with a command to register an Omni Gateway with Anypoint Platform](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-add-gateway.png)

10. Run the copied code block in your terminal window, making sure to first replace `<gateway-name>`
    with a name, such as `my-gw`.

    > [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

11. In Runtime Manager, select **Omni Gateways** from the side navigation panel.

    Your registered Omni Gateway now appears in the list of gateways.

## Run Omni Gateway

To run Omni Gateway, run the following in a terminal window:

```ssh
docker run --rm \
  -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
  -p 8081:8081 \
  mulesoft/flex-gateway
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

A new Omni Gateway instance is now running in your terminal window.

> [!NOTE] The Omni Gateway instance will continue running in the terminal window until the process
> is stopped, or until the window is closed.

## Publish a Simple API

1.  Select **API Manager** from the Anypoint Platform menu.

2.  Click **Add API** > **Add new API**.

3.  From the **Add API** page, select **Omni Gateway** as your runtime.

4.  Select your registered gateway in the **Select a gateway** section.

5.  Click **Next**.

6.  Click **Create New API**.

7.  Specify an API name and select **HTTP API** as the asset type.

8.  Click **Next**.

9.  From the **Endpoint** page, enter the following in the **Implementation URI** field:

    ```none
    https://jsonplaceholder.typicode.com/
    ```

10. Enter `8081` in the **Port** field.

11. Click **Next**.

12. Click **Save & Deploy**.

    Inside the gateway instance Docker container, all HTTP requests made to `localhost` on port
    `8081` are now proxied to the `jsonplaceholder` service.

13. To test the API Instance, run the following command in a new terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  While still in **API Manager**, select **API Instances** from the side navigation panel.

2.  Select the name of the API created in the previous section.

3.  Select **Policies** from the side navigation panel.

4.  In the **Policies** page, click **Add policy**.

    The following screenshot of the **Policies** page highlights the specified options:

    ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-add-policy.png)

5.  Select the **Basic Authentication - Simple** policy.

6.  Click **Next**.

7.  For **User Name**, enter `user`.

8.  For **User Password**, enter `password`.

9.  Click **Apply**.

    The following screenshot of the **Configure Basic Authentication - Simple policy** page
    highlights the specified options:

    ![Configure Basic Authentication Policy page with User Password field selected](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-config-basic-auth.png)

10. To test the API Instance _without_ authentication, run the following `curl` command in the
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

11. To test the API Instance _with_ authentication, run the following command in the terminal
    window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

<!-- document id=021bd34460bf5a8c551cc6d2383ddd048eb0e6bc2967c471d214ea0538d44c67 url=/mulesoft/current/en-us/gateway/latest/gateway-getting-started.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Getting Started with Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The goal of this tutorial is to quickly get started with Omni Gateway. Using Docker, the tutorial
describes how to install, register, and run Omni Gateway in Connected Mode. Additionally, the
tutorial describes how to publish an API that is secured with a basic authentication policy.

## Before You Begin

Before getting started with Omni Gateway, ensure that you have:

- A username and password for your Anypoint Platform organization. If you don’t have Anypoint
  Platform yet, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Linux machine with an x86 processor. M1 and M2 processors are not supported.

  Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

  - Amazon Linux 2023

  - CentOS 8

  - Debian Bookworm

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - Ubuntu Jammy

- A Docker installation. See [Docker Desktop](https://www.docker.com/products/docker-desktop/) for
  an example.

## Download Omni Gateway

To download the Omni Gateway Docker image, run the following command in a terminal window:

```ssh
docker pull mulesoft/flex-gateway:latest
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

## Register Omni Gateway

1.  Create a new directory by running:

    ```ssh
    mkdir flex-registration
    ```

2.  Navigate to the new directory by running:

    ```ssh
    cd flex-registration
    ```

3.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) with your Anypoint username
    and password.

4.  Select **Runtime Manager**.

5.  Click **Omni Gateways** in the side navigation panel.

6.  Click **Self-managed Omni Gateways**.

7.  Click **Add Gateway**.

8.  Select **Docker**.

9.  Copy the code block in the **Register your gateway** section. The code block contains your
    unique organization ID and token.

    The following screenshot of the **Add an Omni Gateway** page highlights the code block to copy:

    ![A code block with a command to register an Omni Gateway with Anypoint Platform](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-add-gateway.png)

10. Run the copied code block in your terminal window, making sure to first replace `<gateway-name>`
    with a name, such as `my-gw`.

    > [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

11. In Runtime Manager, select **Omni Gateways** from the side navigation panel.

    Your registered Omni Gateway now appears in the list of gateways.

## Run Omni Gateway

To run Omni Gateway, run the following in a terminal window:

```ssh
docker run --rm \
  -v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
  -p 8081:8081 \
  mulesoft/flex-gateway
```

> [!NOTE] Use `sudo` if you encounter file permission issues when running this command.

A new Omni Gateway instance is now running in your terminal window.

> [!NOTE] The Omni Gateway instance will continue running in the terminal window until the process
> is stopped, or until the window is closed.

## Publish a Simple API

1.  Select **API Manager** from the Anypoint Platform menu.

2.  Click **Add API** > **Add new API**.

3.  From the **Add API** page, select **Omni Gateway** as your runtime.

4.  Select your registered gateway in the **Select a gateway** section.

5.  Click **Next**.

6.  Click **Create New API**.

7.  Specify an API name and select **HTTP API** as the asset type.

8.  Click **Next**.

9.  From the **Endpoint** page, enter the following in the **Implementation URI** field:

    ```none
    https://jsonplaceholder.typicode.com/
    ```

10. Enter `8081` in the **Port** field.

11. Click **Next**.

12. Click **Save & Deploy**.

    Inside the gateway instance Docker container, all HTTP requests made to `localhost` on port
    `8081` are now proxied to the `jsonplaceholder` service.

13. To test the API Instance, run the following command in a new terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command executes a `GET` request to the API, and then prints the resulting `200` status
    code, indicating success.

## Secure Your API Using the Basic Authentication Policy

1.  While still in **API Manager**, select **API Instances** from the side navigation panel.

2.  Select the name of the API created in the previous section.

3.  Select **Policies** from the side navigation panel.

4.  In the **Policies** page, click **Add policy**.

    The following screenshot of the **Policies** page highlights the specified options:

    ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-add-policy.png)

5.  Select the **Basic Authentication - Simple** policy.

6.  Click **Next**.

7.  For **User Name**, enter `user`.

8.  For **User Password**, enter `password`.

9.  Click **Apply**.

    The following screenshot of the **Configure Basic Authentication - Simple policy** page
    highlights the specified options:

    ![Configure Basic Authentication Policy page with User Password field selected](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-config-basic-auth.png)

10. To test the API Instance _without_ authentication, run the following `curl` command in the
    terminal window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/'
    ```

    The command prints a resulting `401 (Unauthorized)` status code, because the request does not
    include the Authentication context.

11. To test the API Instance _with_ authentication, run the following command in the terminal
    window:

    ```ssh
    curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://localhost:8081/' -u user:password
    ```

    > [!NOTE] The `user` and `password` parameters must match what was specified when you applied
    > the policy via **API Manager**.

    The command prints the resulting `200` status code, indicating success.

## Next Steps

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

<!-- document id=327a3104d2bef28e31d212822acf4422b5ce2bb953b0bcf523ca8c3d6b5c8c04 url=/mulesoft/current/en-us/gateway/1.13/gateway-k8-getting-started.md -->

---
product: Omni Gateway
version: 1.13
---

# Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Omni Gateway in a Kubernetes cluster or an OpenShift cluster, which is based on
Kubernetes. Set up an Omni Gateway deployment that connects to Anypoint Platform, and use the
deployment to route traffic to your API. This guide covers the following high-level tasks:

- Downloading, registering, and deploying Omni Gateway in
  [Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run-token#k8-token) with a token

- Creating a simple API in Anypoint API Manager that runs on your gateway

- Protecting the API with a basic authentication policy that you configure in API Manager

The Omni Gateway deployment process requires a working Kubernetes cluster that you create or that is
provisioned for you by a Kubernetes professional.

Setting up a Kubernetes cluster requires a level of skill and expertise that is _beyond the scope of
this guide to provide_. Cluster configuration in Kubernetes differs significantly by service
provider and platform. For cluster configuration questions, consult documentation from your
Kubernetes service provider or use the
[Kubernetes documentation](https://kubernetes.io/docs/setup/).

If you lack a Kubernetes cluster but want to try out Omni Gateway quickly, without creating a
cluster, see [Getting Started with Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started) (on Docker). That guide
uses Docker exclusively and does not require you to perform any cluster configuration.

## Before You Begin

Before starting the procedures in this guide, ensure that the following prerequisites are in place:

- A username and password for your Anypoint Platform organization. If you do not have an Anypoint
  Platform account, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Docker installation.

  Run `docker --version` from a terminal window to determine if this tool is installed. If you need
  to install Docker, try [Docker Desktop](https://www.docker.com/).

- A minimum Helm version of 3.0.0 is required.

  Run `helm version` from a terminal window to determine if this tool is installed and check the
  version. To install or upgrade, use the [Helm](https://helm.sh/) website.

- The Kubernetes `kubectl` command-line tool.

  Run `kubectl version --output=yaml` from a terminal window to determine if this tool is installed.
  If not, find `kubectl` among the installation tools available through the
  [Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/).

- The `curl` command-line tool.

  Run `curl --version` from a terminal window to determine if this tool is installed. If not, you
  can download it with a package manager for your machine.

## Cluster Requirements

The host for your Kubernetes cluster can be any
[supported Kubernetes provider](https://docs.mulesoft.com/gateway/1.13/review-prerequisites#software-requirements), including common
cloud-based services, such as Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service
(AKS), or Google Kubernetes Engine (GKE).

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

To complete the procedures in this guide, you must create a Kubernetes cluster or use an existing
one for your Omni Gateway deployment. In this guide, you use Helm to deploy Omni Gateway to a
Kubernetes cluster and connect it to Anypoint Platform.

The following minimum requirements apply to a small Kubernetes cluster used for demonstration
purposes in this guide and _do not apply to requirements of a production environment_:

- At least one node.

- Support for the creation of a `Service` resource of the `LoadBalancer` type.

  This requirement avoids deployment errors when you use this guide. However, it is possible to
  customize the `Service` type when deploying a gateway. Omni Gateway supports the following
  services: `ClusterIP`, `NodePort`, `LoadBalancer` (default), `ExternalName`. See the
  `service.type` key in the
  [Helm chart for Omni Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

- Compute resources needed for the deployment procedure are _very unlikely_ to exceed the following
  values (equivalent to the EKS t3.micro instance type):

  - vCPU: 2 vCPUs

  - Memory: 1 GiB

  - Network: Up to 5 Gigabit

  - Max ENI: 2

  - Max IPs: 4

To determine whether your cluster is ready for the [deployment procedure](#deploy-flex), review
[Check Your Cluster](#check-cluster) _before starting_ the deployment. The checks require you to run
a set of `kubectl` commands.

## Step 1: Download the Omni Gateway Image

Use Docker to download the Omni Gateway image from the Docker Hub registry.

This procedure is a prerequisite to registering the Omni Gateway with Anypoint Platform in
[Step 2: Register Omni Gateway](#register-flex). Registration is required during the gateway
deployment through Helm in [Step 4: Deploy and Connect Omni Gateway](#deploy-flex).

1.  Check that Docker is running by executing the following command in a terminal window:

    ```docker
    docker info
    ```

    If you receive an error after executing this command, see the information about
    [Docker troubleshooting](#docker-troubleshooting).

2.  Run the following command in a terminal window:

    ```docker
    docker pull mulesoft/flex-gateway:latest
    ```

    When successful, this command prints a message similar to the following one in your terminal
    window:

    latest: Pulling from mulesoft/flex-gateway Digest: sha256:e55555abcdefg1234567zxynwo33333fadjf
    Status: Image is up to date for mulesoft/flex-gateway:latest
    docker.io/mulesoft/flex-gateway:latest

    Use `sudo` if you encounter permission issues when running this command.

## Step 2: Register Omni Gateway

Register the Omni Gateway image from a terminal window using a temporary token generated by Anypoint
Runtime Manager. This procedure produces a local `registration.yaml` file that contains registration
properties for a named gateway. These properties are incorporated into a Helm chart in
[Step 4: Deploy and Connect Omni Gateway](#deploy-flex).

1.  From a terminal window, prepare a directory for an Omni Gateway registration file
    (`registration.yaml`).

    1.  Create a directory:

        ```mkdir
        mkdir flex-registration
        ```

    2.  Navigate to the new directory:

        ```cd
        cd flex-registration
        ```

2.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) and select **Runtime
    Manager**.

3.  From Runtime Manager, locate the procedure for registering Omni Gateway:

    1.  Click **Omni Gateways** in the side navigation panel.

    2.  Click **Self-managed Omni Gateways**.

    3.  Click **Add Managed Omni-Gateway**.

    4.  Select one of the following environments:

        - **Kubernetes**

        - **OpenShift**

    5.  In the page that opens, locate the command in the **Register your gateway** section.

        Kubernetes Example:

        ![Add registration code block from Add an Omni Gateway page](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-add-gateway-rtm.png)

        The highlighted command block includes your unique organization ID and a temporary token.

4.  In your terminal window, copy the command block from Runtime Manager to your
    `./flex-registration` directory.

    Notice that Runtime Manager provides the required organization and token values.

5.  Before running the command, replace `<gateway-name>` at the end of the command block with a
    _unique_ name for your gateway, such as `my-gateway`.

    The name that you provide for your gateway must be unique within the scope of your Anypoint
    Platform organization and environment. Completing this registration step is required once _and
    allowed no more than once_ per named gateway and organization.

6.  Run the edited command from your terminal window.

    When successful, the command produces a `registration.yaml` in your `./flex-registration`
    directory and displays the following message in your terminal window:

    Starting registration, please be patient. Registration completed, the configuration files were
    written in directory "/registration". For security, modify the file permissions to restrict
    production scenario access to the user running flex.

    Note that the message in the terminal window refers to a `/registration` directory that resides
    within the Docker container.

    Use `sudo` if you encounter file permission issues when running this command. If your token
    expires before you run the command, a `400 Bad Request` error occurs. In this case, you must
    refresh the Runtime Manager page to generate a new token and run the modified command that
    appears on the page.

## Step 3: Add a Repository for the Helm Chart

Add the Omni Gateway chart repository. Note that you can get more information about the properties
of the Helm chart for Omni Gateway in
[ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Add a Helm repository named `flex-gateway` for your Helm chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

## Step 4: Deploy and Connect Omni Gateway

Use Helm to deploy Omni Gateway to a node in your cluster and connect it to Anypoint Platform. After
deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint
Platform.

Before you begin:

Confirm that your Kubernetes cluster is available by following the steps in
[Check Your Cluster](#check-cluster). Review [Cluster Requirements](#kubernetes-cluster-reqs) if you
have not done so already. These prerequisites help avoid deployment errors.

After confirming that your Kubernetes cluster is ready, deploy and connect your gateway:

1.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and `ingress` release if they do not exist. The
    command syntax for the Helm repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

    If you receive an `UPGRADE FAILED` response, see
    [troubleshooting](#troubleshoot-helm-upgrade-failed) information about this issue.

2.  If you want to check the status of the Pod that runs your gateway, execute the following
    `kubectl` command:

    ```kubectl
    kubectl get pods -n gateway
    ```

    The output indicates whether the pod is running successfully in the `gateway` namespace:

    NAME READY STATUS RESTARTS AGE ingress-57bc75cb46-dmkdq 1/1 Running 0 35s

3.  Return to Runtime Manager:

    1.  Select **← Omni Gateways** from the side navigation panel of the **Add an Omni Gateway**
        page.

        ![Choose preferred operating system or environment](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-return-to-gateway-list.png)

    2.  Navigate to your registered gateway in the **Omni Gateways** page:

        ![A table of Omni Gateway details, such as name, ID, status, and last updated timestamp](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-my-gateway-rtm.png)

        You can use the search field in the page to narrow the list of gateways.

    3.  Make sure that the status of your gateway is **Running**.

        If the status is **Not Running**, it’s likely that the cluster configuration is incorrect or
        a network issue has occurred. Check [Troubleshooting](#troubleshooting-k8) for more
        information.

## Step 5: Publish and Deploy a Simple API to Omni Gateway

Create and deploy a simple API to your gateway in Anypoint API Manager:

1.  In Runtime Manager, click the **View APIs** menu option for your gateway to navigate to its
    **View APIs** page.

    ![View APIs menu item for Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-view-apis.png)

    Alternatively, you can navigate to API Manager from the Anypoint Platform menu.

2.  From the page that opens, click **Add API** (and if present, **Add new API**) to navigate to the
    **APIs / Add API** page in API Manager.

3.  From **APIs / Add API**, configure an API by working through the API configuration pages,
    starting with the **Runtime** configuration:

    ![Add API page with Omni Gateway Runtime and my-gateway selected](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-select-gateway-for-api.png)

    1.  From the **Runtime** configuration page, select **Omni Gateway** as your runtime.

    2.  Find and select your gateway in the **Select a gateway** area of the page.

        Use the search field to locate it, if necessary.

    3.  Click **Next** to open the **API** page.

4.  In the **API** configuration page associated with **APIs / Add API**, provide an API name and
    asset type:

    ![A form to select or create a new API](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-api-config-api.png)

    1.  Click **Create new API**.

        The remaining procedures walk you through steps for creating and testing a new HTTP API in
        Anypoint Exchange. Notice, however, that it is also possible to select an existing API from
        Exchange from this page. That process is described in the
        [Add a New API](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#add-a-new-api) in the API
        Manager documentation.

    2.  Provide an API name, such as **my-api**.

    3.  Select **HTTP API** as the asset type.

    4.  Click **Next** to open the **Endpoint** configuration page.

5.  In the **Endpoint** page associated with **APIs / Add API**, set up an endpoint for your API:

    ![A form for configuring endpoint settings](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-api-config-endpoint.png)

    1.  For the **Scheme**, use the default, **HTTP** setting.

        This guide focuses on a simple HTTP API. For HTTPS configuration details, see
        [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config).

    2.  Copy the following URI into the **Implementation URI** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

    3.  Type `80` in the **Port** field.

        The example in this guide uses HTTP port `80` instead of the API Manager default port,
        `8081`, because the created `Service` maps incoming port `80` to target port `80` on the
        Pod. See the `service.http.port` key in the
        [Helm chart for Omni Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

    4.  Click **Next** to open the **Review** page.

6.  In the **Review** page associated with **APIs / Add API**:

    1.  Review your API configuration.

    2.  If necessary, use **Edit** to revise any configurations.

    3.  When your configuration is correct, click **Save & Deploy**.

        Inside the gateway, all incoming HTTP requests on port `80` are proxied to the
        `jsonplaceholder` service.

7.  From a terminal window, test the API instance:

    1.  Get your external IP address and use it to check that your IP redirects to the
        **Implementation URI**:

        ```kubectl
        kubectl -n gateway get services
        ```

        The command returns a result that looks similar to this example:

        NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress LoadBalancer 10.100.145.109
        <123456.aws.com> 80:30524/TCP,443:31710/TCP 7d7h

        The `EXTERNAL-IP` value `<123456.aws.com>` is an example and not an actual value.

    2.  Run the following `curl` command, replacing `<your_external_ip>` with _your_ `EXTERNAL-IP`
        from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command executes a `GET` request to the API and prints a success code:

        200

        You can also run a simpler `curl` command to return an array of JSON objects from the
        service’s `/users` endpoint, for example:

        ```curl
        $ curl http://<your_external_ip>:80/users
        ```

## Step 6: Secure Your API Using the Basic Authentication Policy

Use API Manager to add a basic authentication policy to your API.

1.  In **API Manager**, select **API Instances** from the side navigation panel.

2.  Find and click the name of the API that you created in
    [Step 5: Publish and Deploy a Simple API to Omni Gateway](#create-api), such as **my-api**.

3.  Navigate to the **Policies** page for your API:

    1.  Select **Policies** from the side navigation panel.

    2.  On the **Policies** page, click **Add policy**.

        ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-add-policy.png)

4.  In the page that opens, find the **Security** policy called **Basic Authentication - Simple**
    policy.

    ![A form that empowers you to choose from a range of security policies](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-basic-auth.png)

    Be careful to avoid selecting the similarly named policy for LDAP.

5.  Click **Next**.

6.  Configure a Basic Authentication policy:

    ![Screenshot of 'Configure Basic Authentication - Simple policy' page](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-config-basic-auth.png)

    1.  For **User Name**, enter `user` instead of your real user name.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    2.  For **User Password**, enter `pw`.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    3.  Click **Apply**.

7.  Test the API instance:

    1.  Use `kubectl` to get your external IP address again so that you can use it in the next step:

        ```kubectl
        kubectl -n gateway get services
        ```

    2.  Run the following `curl` a command _without_ authentication parameters, replacing
        `<your_external_ip>` with the `EXTERNAL-IP` returned by preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command returns a `401` because the URI lacks authentication parameters:

        401

    3.  Run the following `curl` a command _with_ authentication parameters, replacing
        `<your_external_ip>` with your `EXTERNAL-IP` from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users' -u user:pw
        ```

        The command prints the resulting `200` status code, indicating success:

        200

        The `user` and `password` parameters (`user:pw`) must match the values you specified when
        you applied the policy. If you enter incorrect authentication parameters, the following
        error occurs:

        401

        To address the error, run the command with the correct authentication parameters, or return
        to the policy configuration page for your API in API Gateway, edit the policy configuration,
        and rerun the `curl` commands.

        ![Automated and API-level policy settings](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-config-basic-auth-edit-dialogue.png)

        The page for editing the credentials looks similar to this one:

        ![A form with fields to input a username and password](/mulesoft/current/en-us/gateway/1.13/_images/gateway-quickstart-k8-config-basic-auth-edit.png)

## Troubleshooting

If you encounter an error when running a command, check for troubleshooting information:

[Docker Command Issues](#docker-troubleshooting) | [Helm Command Issues](#helm-troubleshooting)

### Docker Command Issues

Troubleshoot errors returned by a `docker` command:

- [Docker Daemon Error](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

#### Docker Daemon Error

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

#### Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add an Omni
  Gateway** page for Kubernetes and rerun the registration command.

### Helm Command Issues

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

#### Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Omni Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See [Register Omni Gateway](#register-flex)
for an example of the registration command.

#### Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

#### Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Omni Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

#### Failed to Install CRD

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

## Check Your Cluster

Before deploying Omni Gateway to your Kubernetes cluster in
[Step 4: Deploy and Connect Omni Gateway](#deploy-flex), ensure that your cluster is ready. Use
`kubectl` to list and select (use) a cluster and to get a list of nodes that the cluster uses. If
any steps in this section fail, the deployment process is likely to produce errors.

To prevent potential timeout and connectivity errors when running procedures in this guide, your
cluster must meet the [Cluster Requirements](#kubernetes-cluster-reqs).

1.  Run `kubectl config get-contexts` to list the clusters, for example:

    ```kubectl
    kubectl config get-contexts
    ```

    This command is particularly helpful if you have multiple Kubernetes clusters. You can use the
    command to get the name of the correct cluster. For example, assume that you have a variety of
    clusters (`my-cluster`, `my-aks`, `my-gke`, `my-eks`). The command prints a list of your
    clusters.

    The following _example_ shows a list of clusters produced by the command:

    CURRENT NAME CLUSTER AUTHINFO NAMESPACE my-cluster my-cluster my-cluster1 my-aks my-aks my-aks
    my-gke my-gke my-gke my-eks my-eks my-eks

    If your cluster is not listed and you are using a custom cluster context file on your machine to
    connect to your cluster, you might need to add its path to a `KUBECONFIG` environment variable
    that points to that file. By default, `kubectl` searches for a file named `config` in the
    `$HOME/.kube` directory. That file lists each `context`, which provides properties such as the
    cluster name, user, and certificate authority data.

    You can check by running `echo $KUBECONFIG` from your terminal window, which prints a
    environment variable’s value, similar to this example:

    {KUBECONFIG}:/Users/me/.kube/config:/Users/me/.kube/additional-clusters/my-gke:/Users/me/.kube/additional-clusters/my-aks:/Users/me/.kube/additional-clusters/my-eks

    Adding the path to any additional cluster context files on your machine enables the
    `kubectl config get-contexts` command to list the cluster contexts and for you to use them.

    For more detail, see the
    [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
    about the `kubeconfig` file.

2.  Provide the name of a cluster into which you plan to deploy your gateway.

    The following example uses the cluster `my-eks`, identified in the cluster list example:

    kubectl config use-context my-eks

    The command switches to the selected cluster context and prints a message similar to this one:

    Switched to context "my-eks".

    If you receive an error that begins `error: no context exists with the name`, ensure you are
    using the `NAME` value of the cluster listed by `kubectl config get-contexts` and not the
    `CLUSTER` value.

3.  Check that your cluster has one or more nodes:

    ```kubectl
    kubectl get nodes
    ```

    The command returns a output similar to this example:

    NAME STATUS ROLES AGE VERSION ip-192-168-70-170 Ready <none> 17h v1.x.x ip-192-168-9-230 Ready
    <none> 17h v1.x.x

    Make sure that at least one node is in the `Ready` status.

4.  If your cluster is not ready, correct the cluster configuration.

    Alternatively, try the Docker-only guide,
    [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started), which does not use a
    Kubernetes cluster, and skip the next steps.

5.  If you have not started the Omni Gateway setup procedures yet, review
    [Cluster Requirements](#kubernetes-cluster-reqs) before proceeding to
    [Step 1: Download the Omni Gateway Image](#download-flex).

6.  If you have successfully completed all the procedures for downloading and registering your
    gateway with Docker and adding a repository for your Helm chart, and you are ready to begin the
    deployment procedure, go to [Step 4: Deploy and Connect Omni Gateway](#deploy-flex).

## Next Steps

Learn other ways to set up and configure Omni Gateway for a Kubernetes cluster, and review other
policy configuration options.

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

- [Configuring Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-configure)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management)

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

<!-- document id=52e91092e09abb3b88913a2dda65d8444fbfcb650919fffad67af132079d0534 url=/mulesoft/current/en-us/gateway/latest/gateway-k8-getting-started.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Get started with Omni Gateway in a Kubernetes cluster or an OpenShift cluster, which is based on
Kubernetes. Set up an Omni Gateway deployment that connects to Anypoint Platform, and use the
deployment to route traffic to your API. This guide covers the following high-level tasks:

- Downloading, registering, and deploying Omni Gateway in
  [Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run-token#k8-token) with a token

- Creating a simple API in Anypoint API Manager that runs on your gateway

- Protecting the API with a basic authentication policy that you configure in API Manager

The Omni Gateway deployment process requires a working Kubernetes cluster that you create or that is
provisioned for you by a Kubernetes professional.

Setting up a Kubernetes cluster requires a level of skill and expertise that is _beyond the scope of
this guide to provide_. Cluster configuration in Kubernetes differs significantly by service
provider and platform. For cluster configuration questions, consult documentation from your
Kubernetes service provider or use the
[Kubernetes documentation](https://kubernetes.io/docs/setup/).

If you lack a Kubernetes cluster but want to try out Omni Gateway quickly, without creating a
cluster, see [Getting Started with Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started) (on Docker). That guide
uses Docker exclusively and does not require you to perform any cluster configuration.

## Before You Begin

Before starting the procedures in this guide, ensure that the following prerequisites are in place:

- A username and password for your Anypoint Platform organization. If you do not have an Anypoint
  Platform account, [create a Trial organization](https://anypoint.mulesoft.com/login/signup) on
  Anypoint Platform.

- A Docker installation.

  Run `docker --version` from a terminal window to determine if this tool is installed. If you need
  to install Docker, try [Docker Desktop](https://www.docker.com/).

- A minimum Helm version of 3.0.0 is required.

  Run `helm version` from a terminal window to determine if this tool is installed and check the
  version. To install or upgrade, use the [Helm](https://helm.sh/) website.

- The Kubernetes `kubectl` command-line tool.

  Run `kubectl version --output=yaml` from a terminal window to determine if this tool is installed.
  If not, find `kubectl` among the installation tools available through the
  [Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/).

- The `curl` command-line tool.

  Run `curl --version` from a terminal window to determine if this tool is installed. If not, you
  can download it with a package manager for your machine.

## Cluster Requirements

The host for your Kubernetes cluster can be any
[supported Kubernetes provider](https://docs.mulesoft.com/gateway/latest/review-prerequisites#software-requirements), including common
cloud-based services, such as Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service
(AKS), or Google Kubernetes Engine (GKE).

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

To complete the procedures in this guide, you must create a Kubernetes cluster or use an existing
one for your Omni Gateway deployment. In this guide, you use Helm to deploy Omni Gateway to a
Kubernetes cluster and connect it to Anypoint Platform.

The following minimum requirements apply to a small Kubernetes cluster used for demonstration
purposes in this guide and _do not apply to requirements of a production environment_:

- At least one node.

- Support for the creation of a `Service` resource of the `LoadBalancer` type.

  This requirement avoids deployment errors when you use this guide. However, it is possible to
  customize the `Service` type when deploying a gateway. Omni Gateway supports the following
  services: `ClusterIP`, `NodePort`, `LoadBalancer` (default), `ExternalName`. See the
  `service.type` key in the
  [Helm chart for Omni Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

- Compute resources needed for the deployment procedure are _very unlikely_ to exceed the following
  values (equivalent to the EKS t3.micro instance type):

  - vCPU: 2 vCPUs

  - Memory: 1 GiB

  - Network: Up to 5 Gigabit

  - Max ENI: 2

  - Max IPs: 4

To determine whether your cluster is ready for the [deployment procedure](#deploy-flex), review
[Check Your Cluster](#check-cluster) _before starting_ the deployment. The checks require you to run
a set of `kubectl` commands.

## Step 1: Download the Omni Gateway Image

Use Docker to download the Omni Gateway image from the Docker Hub registry.

This procedure is a prerequisite to registering the Omni Gateway with Anypoint Platform in
[Step 2: Register Omni Gateway](#register-flex). Registration is required during the gateway
deployment through Helm in [Step 4: Deploy and Connect Omni Gateway](#deploy-flex).

1.  Check that Docker is running by executing the following command in a terminal window:

    ```docker
    docker info
    ```

    If you receive an error after executing this command, see the information about
    [Docker troubleshooting](#docker-troubleshooting).

2.  Run the following command in a terminal window:

    ```docker
    docker pull mulesoft/flex-gateway:latest
    ```

    When successful, this command prints a message similar to the following one in your terminal
    window:

    latest: Pulling from mulesoft/flex-gateway Digest: sha256:e55555abcdefg1234567zxynwo33333fadjf
    Status: Image is up to date for mulesoft/flex-gateway:latest
    docker.io/mulesoft/flex-gateway:latest

    Use `sudo` if you encounter permission issues when running this command.

## Step 2: Register Omni Gateway

Register the Omni Gateway image from a terminal window using a temporary token generated by Anypoint
Runtime Manager. This procedure produces a local `registration.yaml` file that contains registration
properties for a named gateway. These properties are incorporated into a Helm chart in
[Step 4: Deploy and Connect Omni Gateway](#deploy-flex).

1.  From a terminal window, prepare a directory for an Omni Gateway registration file
    (`registration.yaml`).

    1.  Create a directory:

        ```mkdir
        mkdir flex-registration
        ```

    2.  Navigate to the new directory:

        ```cd
        cd flex-registration
        ```

2.  Log in to [Anypoint Platform](https://anypoint.mulesoft.com/login/) and select **Runtime
    Manager**.

3.  From Runtime Manager, locate the procedure for registering Omni Gateway:

    1.  Click **Omni Gateways** in the side navigation panel.

    2.  Click **Self-managed Omni Gateways**.

    3.  Click **Add Managed Omni-Gateway**.

    4.  Select one of the following environments:

        - **Kubernetes**

        - **OpenShift**

    5.  In the page that opens, locate the command in the **Register your gateway** section.

        Kubernetes Example:

        ![Add registration code block from Add an Omni Gateway page](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-add-gateway-rtm.png)

        The highlighted command block includes your unique organization ID and a temporary token.

4.  In your terminal window, copy the command block from Runtime Manager to your
    `./flex-registration` directory.

    Notice that Runtime Manager provides the required organization and token values.

5.  Before running the command, replace `<gateway-name>` at the end of the command block with a
    _unique_ name for your gateway, such as `my-gateway`.

    The name that you provide for your gateway must be unique within the scope of your Anypoint
    Platform organization and environment. Completing this registration step is required once _and
    allowed no more than once_ per named gateway and organization.

6.  Run the edited command from your terminal window.

    When successful, the command produces a `registration.yaml` in your `./flex-registration`
    directory and displays the following message in your terminal window:

    Starting registration, please be patient. Registration completed, the configuration files were
    written in directory "/registration". For security, modify the file permissions to restrict
    production scenario access to the user running flex.

    Note that the message in the terminal window refers to a `/registration` directory that resides
    within the Docker container.

    Use `sudo` if you encounter file permission issues when running this command. If your token
    expires before you run the command, a `400 Bad Request` error occurs. In this case, you must
    refresh the Runtime Manager page to generate a new token and run the modified command that
    appears on the page.

## Step 3: Add a Repository for the Helm Chart

Add the Omni Gateway chart repository. Note that you can get more information about the properties
of the Helm chart for Omni Gateway in
[ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Add a Helm repository named `flex-gateway` for your Helm chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

## Step 4: Deploy and Connect Omni Gateway

Use Helm to deploy Omni Gateway to a node in your cluster and connect it to Anypoint Platform. After
deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint
Platform.

Before you begin:

Confirm that your Kubernetes cluster is available by following the steps in
[Check Your Cluster](#check-cluster). Review [Cluster Requirements](#kubernetes-cluster-reqs) if you
have not done so already. These prerequisites help avoid deployment errors.

After confirming that your Kubernetes cluster is ready, deploy and connect your gateway:

1.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and `ingress` release if they do not exist. The
    command syntax for the Helm repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

    If you receive an `UPGRADE FAILED` response, see
    [troubleshooting](#troubleshoot-helm-upgrade-failed) information about this issue.

2.  If you want to check the status of the Pod that runs your gateway, execute the following
    `kubectl` command:

    ```kubectl
    kubectl get pods -n gateway
    ```

    The output indicates whether the pod is running successfully in the `gateway` namespace:

    NAME READY STATUS RESTARTS AGE ingress-57bc75cb46-dmkdq 1/1 Running 0 35s

3.  Return to Runtime Manager:

    1.  Select **← Omni Gateways** from the side navigation panel of the **Add an Omni Gateway**
        page.

        ![Choose preferred operating system or environment](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-return-to-gateway-list.png)

    2.  Navigate to your registered gateway in the **Omni Gateways** page:

        ![A table of Omni Gateway details, such as name, ID, status, and last updated timestamp](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-my-gateway-rtm.png)

        You can use the search field in the page to narrow the list of gateways.

    3.  Make sure that the status of your gateway is **Running**.

        If the status is **Not Running**, it’s likely that the cluster configuration is incorrect or
        a network issue has occurred. Check [Troubleshooting](#troubleshooting-k8) for more
        information.

## Step 5: Publish and Deploy a Simple API to Omni Gateway

Create and deploy a simple API to your gateway in Anypoint API Manager:

1.  In Runtime Manager, click the **View APIs** menu option for your gateway to navigate to its
    **View APIs** page.

    ![View APIs menu item for Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-view-apis.png)

    Alternatively, you can navigate to API Manager from the Anypoint Platform menu.

2.  From the page that opens, click **Add API** (and if present, **Add new API**) to navigate to the
    **APIs / Add API** page in API Manager.

3.  From **APIs / Add API**, configure an API by working through the API configuration pages,
    starting with the **Runtime** configuration:

    ![Add API page with Omni Gateway Runtime and my-gateway selected](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-select-gateway-for-api.png)

    1.  From the **Runtime** configuration page, select **Omni Gateway** as your runtime.

    2.  Find and select your gateway in the **Select a gateway** area of the page.

        Use the search field to locate it, if necessary.

    3.  Click **Next** to open the **API** page.

4.  In the **API** configuration page associated with **APIs / Add API**, provide an API name and
    asset type:

    ![A form to select or create a new API](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-api-config-api.png)

    1.  Click **Create new API**.

        The remaining procedures walk you through steps for creating and testing a new HTTP API in
        Anypoint Exchange. Notice, however, that it is also possible to select an existing API from
        Exchange from this page. That process is described in the
        [Add a New API](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#add-a-new-api) in the API
        Manager documentation.

    2.  Provide an API name, such as **my-api**.

    3.  Select **HTTP API** as the asset type.

    4.  Click **Next** to open the **Endpoint** configuration page.

5.  In the **Endpoint** page associated with **APIs / Add API**, set up an endpoint for your API:

    ![A form for configuring endpoint settings](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-api-config-endpoint.png)

    1.  For the **Scheme**, use the default, **HTTP** setting.

        This guide focuses on a simple HTTP API. For HTTPS configuration details, see
        [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tls-config).

    2.  Copy the following URI into the **Implementation URI** field:

        ```none
        https://jsonplaceholder.typicode.com/
        ```

    3.  Type `80` in the **Port** field.

        The example in this guide uses HTTP port `80` instead of the API Manager default port,
        `8081`, because the created `Service` maps incoming port `80` to target port `80` on the
        Pod. See the `service.http.port` key in the
        [Helm chart for Omni Gateway](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

    4.  Click **Next** to open the **Review** page.

6.  In the **Review** page associated with **APIs / Add API**:

    1.  Review your API configuration.

    2.  If necessary, use **Edit** to revise any configurations.

    3.  When your configuration is correct, click **Save & Deploy**.

        Inside the gateway, all incoming HTTP requests on port `80` are proxied to the
        `jsonplaceholder` service.

7.  From a terminal window, test the API instance:

    1.  Get your external IP address and use it to check that your IP redirects to the
        **Implementation URI**:

        ```kubectl
        kubectl -n gateway get services
        ```

        The command returns a result that looks similar to this example:

        NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress LoadBalancer 10.100.145.109
        <123456.aws.com> 80:30524/TCP,443:31710/TCP 7d7h

        The `EXTERNAL-IP` value `<123456.aws.com>` is an example and not an actual value.

    2.  Run the following `curl` command, replacing `<your_external_ip>` with _your_ `EXTERNAL-IP`
        from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command executes a `GET` request to the API and prints a success code:

        200

        You can also run a simpler `curl` command to return an array of JSON objects from the
        service’s `/users` endpoint, for example:

        ```curl
        $ curl http://<your_external_ip>:80/users
        ```

## Step 6: Secure Your API Using the Basic Authentication Policy

Use API Manager to add a basic authentication policy to your API.

1.  In **API Manager**, select **API Instances** from the side navigation panel.

2.  Find and click the name of the API that you created in
    [Step 5: Publish and Deploy a Simple API to Omni Gateway](#create-api), such as **my-api**.

3.  Navigate to the **Policies** page for your API:

    1.  Select **Policies** from the side navigation panel.

    2.  On the **Policies** page, click **Add policy**.

        ![Add Policy page with Add policy button](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-add-policy.png)

4.  In the page that opens, find the **Security** policy called **Basic Authentication - Simple**
    policy.

    ![A form that empowers you to choose from a range of security policies](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-basic-auth.png)

    Be careful to avoid selecting the similarly named policy for LDAP.

5.  Click **Next**.

6.  Configure a Basic Authentication policy:

    ![Screenshot of 'Configure Basic Authentication - Simple policy' page](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-config-basic-auth.png)

    1.  For **User Name**, enter `user` instead of your real user name.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    2.  For **User Password**, enter `pw`.

        If the field is pre-populated with a value, you can keep the value or change it to the
        suggested value.

    3.  Click **Apply**.

7.  Test the API instance:

    1.  Use `kubectl` to get your external IP address again so that you can use it in the next step:

        ```kubectl
        kubectl -n gateway get services
        ```

    2.  Run the following `curl` a command _without_ authentication parameters, replacing
        `<your_external_ip>` with the `EXTERNAL-IP` returned by preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
        ```

        The command returns a `401` because the URI lacks authentication parameters:

        401

    3.  Run the following `curl` a command _with_ authentication parameters, replacing
        `<your_external_ip>` with your `EXTERNAL-IP` from the preceding step:

        ```curl
        curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users' -u user:pw
        ```

        The command prints the resulting `200` status code, indicating success:

        200

        The `user` and `password` parameters (`user:pw`) must match the values you specified when
        you applied the policy. If you enter incorrect authentication parameters, the following
        error occurs:

        401

        To address the error, run the command with the correct authentication parameters, or return
        to the policy configuration page for your API in API Gateway, edit the policy configuration,
        and rerun the `curl` commands.

        ![Automated and API-level policy settings](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-config-basic-auth-edit-dialogue.png)

        The page for editing the credentials looks similar to this one:

        ![A form with fields to input a username and password](/mulesoft/current/en-us/gateway/latest/_images/gateway-quickstart-k8-config-basic-auth-edit.png)

## Troubleshooting

If you encounter an error when running a command, check for troubleshooting information:

[Docker Command Issues](#docker-troubleshooting) | [Helm Command Issues](#helm-troubleshooting)

### Docker Command Issues

Troubleshoot errors returned by a `docker` command:

- [Docker Daemon Error](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

#### Docker Daemon Error

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

#### Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add an Omni
  Gateway** page for Kubernetes and rerun the registration command.

### Helm Command Issues

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

#### Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Omni Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See [Register Omni Gateway](#register-flex)
for an example of the registration command.

#### Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

#### Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Omni Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

#### Failed to Install CRD

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

See [Cluster Requirements](#kubernetes-cluster-reqs) for additional information.

## Check Your Cluster

Before deploying Omni Gateway to your Kubernetes cluster in
[Step 4: Deploy and Connect Omni Gateway](#deploy-flex), ensure that your cluster is ready. Use
`kubectl` to list and select (use) a cluster and to get a list of nodes that the cluster uses. If
any steps in this section fail, the deployment process is likely to produce errors.

To prevent potential timeout and connectivity errors when running procedures in this guide, your
cluster must meet the [Cluster Requirements](#kubernetes-cluster-reqs).

1.  Run `kubectl config get-contexts` to list the clusters, for example:

    ```kubectl
    kubectl config get-contexts
    ```

    This command is particularly helpful if you have multiple Kubernetes clusters. You can use the
    command to get the name of the correct cluster. For example, assume that you have a variety of
    clusters (`my-cluster`, `my-aks`, `my-gke`, `my-eks`). The command prints a list of your
    clusters.

    The following _example_ shows a list of clusters produced by the command:

    CURRENT NAME CLUSTER AUTHINFO NAMESPACE my-cluster my-cluster my-cluster1 my-aks my-aks my-aks
    my-gke my-gke my-gke my-eks my-eks my-eks

    If your cluster is not listed and you are using a custom cluster context file on your machine to
    connect to your cluster, you might need to add its path to a `KUBECONFIG` environment variable
    that points to that file. By default, `kubectl` searches for a file named `config` in the
    `$HOME/.kube` directory. That file lists each `context`, which provides properties such as the
    cluster name, user, and certificate authority data.

    You can check by running `echo $KUBECONFIG` from your terminal window, which prints a
    environment variable’s value, similar to this example:

    {KUBECONFIG}:/Users/me/.kube/config:/Users/me/.kube/additional-clusters/my-gke:/Users/me/.kube/additional-clusters/my-aks:/Users/me/.kube/additional-clusters/my-eks

    Adding the path to any additional cluster context files on your machine enables the
    `kubectl config get-contexts` command to list the cluster contexts and for you to use them.

    For more detail, see the
    [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
    about the `kubeconfig` file.

2.  Provide the name of a cluster into which you plan to deploy your gateway.

    The following example uses the cluster `my-eks`, identified in the cluster list example:

    kubectl config use-context my-eks

    The command switches to the selected cluster context and prints a message similar to this one:

    Switched to context "my-eks".

    If you receive an error that begins `error: no context exists with the name`, ensure you are
    using the `NAME` value of the cluster listed by `kubectl config get-contexts` and not the
    `CLUSTER` value.

3.  Check that your cluster has one or more nodes:

    ```kubectl
    kubectl get nodes
    ```

    The command returns a output similar to this example:

    NAME STATUS ROLES AGE VERSION ip-192-168-70-170 Ready <none> 17h v1.x.x ip-192-168-9-230 Ready
    <none> 17h v1.x.x

    Make sure that at least one node is in the `Ready` status.

4.  If your cluster is not ready, correct the cluster configuration.

    Alternatively, try the Docker-only guide,
    [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started), which does not use a
    Kubernetes cluster, and skip the next steps.

5.  If you have not started the Omni Gateway setup procedures yet, review
    [Cluster Requirements](#kubernetes-cluster-reqs) before proceeding to
    [Step 1: Download the Omni Gateway Image](#download-flex).

6.  If you have successfully completed all the procedures for downloading and registering your
    gateway with Docker and adding a repository for your Helm chart, and you are ready to begin the
    deployment procedure, go to [Step 4: Deploy and Connect Omni Gateway](#deploy-flex).

## Next Steps

Learn other ways to set up and configure Omni Gateway for a Kubernetes cluster, and review other
policy configuration options.

- [Requirements and Limits for Omni Gateway](https://docs.mulesoft.com/gateway/latest/review-prerequisites)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

- [Configuring Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-configure)

- [Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management)

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

<!-- document id=25133f53a1d896aed0aeff268df9c75a58bc5bf4c08084baa25ae8839fb22594 url=/mulesoft/current/en-us/gateway/latest/policies-included-google-model-armor-guardrails.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, content safety, google, google cloud, model armor, guardrails, redaction
---

# Google Model Armor Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Google Model Armor Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates OpenAI and Gemini format LLM prompts and responses against a Google Cloud Model Armor template, blocking or redacting flagged content</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.14.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/google-model-armor-guardrails-release-notes">Google Model Armor Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content blocked by Google Model Armor</p></td></tr><tr><td><p>503 - Service Unavailable: Model Armor or the Google OAuth token endpoint call failed, timed out, or returned no usable verdict (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The Google Model Armor Guardrails policy provides content moderation for LLMs by evaluating prompts
and responses against a
[Google Cloud Model Armor](https://cloud.google.com/security/products/model-armor) template. The
policy calls the Model Armor `sanitizeUserPrompt` operation in the request phase and the
`sanitizeModelResponse` operation in the response phase, and enforces the returned verdict at the
gateway before the request reaches the upstream LLM or before the response is returned to the
client.

Which Model Armor filters run and how they behave (filter selection, confidence levels, Sensitive
Data Protection (SDP) configuration, and filter version) is owned by your Model Armor template in
Google Cloud, not the policy. The policy references the template, authenticates with a Google Cloud
service account, and turns the Model Armor verdict into a gateway action:

- **Allow**: Content with no filter match is forwarded unchanged.

- **Redact**: When SDP de-identification is enabled, sensitive content is replaced with the Model
  Armor de-identified text, then forwarded.

- **Reject**: Content that matches a filter is rejected with HTTP status `403`.

The policy operates in two independent phases:

- **Request phase**: Sends the recent conversation history of the request to `sanitizeUserPrompt`.
  Rejected prompts never reach the LLM.

- **Response phase**: Sends the LLM completion to `sanitizeModelResponse` before returning it to the
  client.

Both phases are enabled by default. Every moderated request and response emits observability headers
and metrics, and rejections record a policy violation.

## Before You Begin

Before configuring this policy, you need:

1.  **A Google Cloud project with the Model Armor API enabled.**

2.  **A Model Armor template** in that project that defines the filters to apply. You can use one
    template for both phases or separate templates for prompts and responses.

3.  **A Google Cloud service account key** (JSON) for a service account that has permission to call
    Model Armor sanitize operations on the template’s project and location. If the template uses
    advanced SDP configuration (linked inspect or de-identify templates), the service account also
    needs the Sensitive Data Protection permissions those templates require. For the required roles,
    see the
    [Model Armor documentation](https://cloud.google.com/security-command-center/docs/model-armor-overview).

4.  **The regional Model Armor endpoint** that matches the template’s location, for example,
    `https://modelarmor.us-central1.rep.googleapis.com`.

Ensure that Omni Gateway can reach the Model Armor endpoint and the Google OAuth token endpoint
(`https://oauth2.googleapis.com`) outbound.

The policy reads the `x-input-format` header, which the LLM proxy sets, to identify the caller’s LLM
format: `openai` or `gemini`. Requests with a missing or different format value, non-POST requests,
and requests without a JSON body pass through unscanned.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Google Model Armor Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Model Armor Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Regional Model Armor API base URL, for example, <code>https://modelarmor.us-central1.rep.googleapis.com</code>. The region must match the value of <strong>Location</strong>. The policy doesn’t validate this match. A mismatch surfaces as a Model Armor API error at runtime.</p></div></div></td></tr><tr><td><div><div><p>Service Account Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Google Cloud service account key JSON that the policy uses to obtain an OAuth 2.0 access token for the Model Armor API. This value is sensitive and is never logged.</p></div></div></td></tr><tr><td><div><div><p>Project</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Google Cloud project ID that owns the Model Armor template.</p></div></div></td></tr><tr><td><div><div><p>Location</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Model Armor location, either a region (for example, <code>us-central1</code> or <code>europe-west2</code>) or a multi-region (<code>us</code> or <code>eu</code>). Must match the region of <strong>Model Armor Endpoint</strong>.</p></div></div></td></tr><tr><td><div><div><p>Template</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Model Armor template ID. The policy combines <strong>Project</strong>, <strong>Location</strong>, and <strong>Template</strong> into the template resource name <code>projects/{project}/locations/{location}/templates/{template}</code>. Applies to both phases unless overridden by <strong>Request Template</strong> or <strong>Response Template</strong>.</p></div></div></td></tr><tr><td><div><div><p>Google OAuth Token Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Google OAuth 2.0 token endpoint used to obtain the access token. Set this to <code>https://oauth2.googleapis.com</code> unless you use a non-default OAuth host.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default), the policy evaluates the prompt with <code>sanitizeUserPrompt</code> before forwarding it to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default), the policy evaluates the LLM completion with <code>sanitizeModelResponse</code> before returning it to the client.</p></div><div><p>Streaming responses (<code>text/event-stream</code>) are also scanned. The policy buffers the entire stream and holds the response until the scan completes. This breaks the streaming experience for the client and increases latency and memory use.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Request Template</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Model Armor template ID to use for the request phase instead of <strong>Template</strong>.</p></div></div></td></tr><tr><td><div><div><p>Response Template</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Model Armor template ID to use for the response phase instead of <strong>Template</strong>.</p></div></div></td></tr><tr><td><div><div><p>Enable Multi-Language Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, the policy sets the Model Armor multi-language detection flag on each sanitize call so that non-English content is screened. Default: disabled.</p></div></div></td></tr><tr><td><div><div><p>De-identify Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled and the request-phase template uses advanced SDP with a de-identify template, an SDP match replaces the prompt with the de-identified text instead of rejecting it. Default: disabled. See <a href="#sdp-de-identification">SDP De-identification</a>.</p></div></div></td></tr><tr><td><div><div><p>De-identify Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled and the response-phase template uses advanced SDP with a de-identify template, an SDP match replaces the completion with the de-identified text instead of rejecting it. Applies to non-streaming responses only. On a streaming response, an SDP match is rejected. Default: disabled. See <a href="#sdp-de-identification">SDP De-identification</a>.</p></div></div></td></tr><tr><td><div><div><p>Inspect Only</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, the policy reports verdicts in the observability headers but never rejects traffic. Use this to observe what Model Armor would block before enforcing a template. Default: disabled.</p></div></div></td></tr><tr><td><div><div><p>History Depth</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum number of recent conversation messages included in the request-phase scan. 0 (default) scans the full conversation history. If the scanned text exceeds the Model Armor size limits, Model Armor skips detection and the policy forwards the request unscanned, with skip_detection in the reason header. Set this value to keep long conversations within he Model Armor size limits.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Timeout in milliseconds for each Model Armor sanitize call and each OAuth token call. Must be between <code>1000</code> and <code>30000</code>. Values outside this range are set to the nearest limit. Default: <code>5000</code>.</p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Model Armor call or the OAuth token call fails, times out, or returns no usable verdict:</p></div><div><ul><li><p>Disabled (default): Rejects with HTTP <code>503</code>.</p></li><li><p>Enabled: Allows traffic to proceed unscanned. The failure reason is still emitted in the reason header.</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The Google Model Armor Guardrails policy integrates with Google Cloud Model Armor to evaluate LLM
prompts and responses.

### Authentication

The policy authenticates to Model Armor with an OAuth 2.0 access token that it obtains from the
Google OAuth token endpoint by using the configured service account key. The token is scoped to
`https://www.googleapis.com/auth/cloud-platform`, cached per gateway replica, and refreshed before
it expires.

The first request on each replica, and each token refresh, makes an extra call to the token endpoint
before the sanitize call. Each call is bounded by **API Timeout (ms)**, so these requests can take
up to twice the timeout before the fail-open or fail-closed behavior applies. Subsequent requests
use the cached token and add no authentication latency.

A token failure, such as an expired or revoked service account key, is handled the same way as a
Model Armor call failure.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when Moderate Request is enabled):

    1.  The policy resolves the caller’s LLM format from the `x-input-format` header. Non-POST
        requests, unsupported formats, and non-JSON or empty bodies pass through unscanned.

    2.  The policy extracts the conversation text from the request body, limited by **History
        Depth**. For OpenAI, the policy supports the Chat Completions and Responses APIs. For
        Gemini, the policy supports `generateContent` and `streamGenerateContent` request bodies. If
        no text can be extracted, the request passes through unscanned.

    3.  The policy sends the text to `sanitizeUserPrompt` with the request-phase template.

    4.  The policy enforces the returned verdict. See [Outcomes and Actions](#outcomes-and-actions).

2.  **Response Phase** (when Moderate Response is enabled):

    1.  The policy buffers the LLM response and extracts the completion text. For streaming
        responses, the policy reassembles the completion from the stream’s chunks. If no completion
        text can be extracted, the response passes through unscanned.

    2.  The policy sends the completion to `sanitizeModelResponse` with the response-phase template.

    3.  The policy enforces the returned verdict. See [Outcomes and Actions](#outcomes-and-actions).

        > [!NOTE] Streaming responses (`text/event-stream`) are buffered and scanned when Moderate
        > Response is enabled. The client doesn’t receive the response until the scan completes. For
        > Gemini, only streaming with `alt=sse` is scanned.

If the request phase rejects the request, the response phase doesn’t run.

### Outcomes and Actions

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Model Armor Verdict</th><th>Action</th><th>Effect</th></tr></thead><tbody><tr><td><div><div><p>No match</p></div></div></td><td><div><div><p>Allow</p></div></div></td><td><div><div><p>Content is forwarded unchanged.</p></div></div></td></tr><tr><td><div><div><p>Match on SDP only, with de-identification enabled for the phase</p></div></div></td><td><div><div><p>Redact</p></div></div></td><td><div><div><p>The prompt or completion is replaced with the de-identified text that Model Armor returns, and traffic continues. See <a href="#sdp-de-identification">SDP De-identification</a>.</p></div></div></td></tr><tr><td><div><div><p>Match</p></div></div></td><td><div><div><p>Reject</p></div></div></td><td><div><div><p>The request phase returns an HTTP <code>403</code> response instead of calling the LLM. The response phase rewrites the LLM response to an HTTP <code>403</code> response. A policy violation is recorded.</p></div></div></td></tr><tr><td><div><div><p>Match, with Inspect Only enabled</p></div></div></td><td><div><div><p>Allow</p></div></div></td><td><div><div><p>Traffic continues. The matched filters populate the reason header.</p></div></div></td></tr><tr><td><div><div><p>Error, timeout, or no usable verdict</p></div></div></td><td><div><div><p>Depends on Fail Open</p></div></div></td><td><div><div><p>When fail-open is disabled, the policy returns an HTTP <code>503</code> response and records a policy violation. When fail-open is enabled, traffic passes through unscanned.</p></div></div></td></tr></tbody></table>

If Model Armor skips detection for a filter, for example, because the content exceeds the Model
Armor size limits, the skip doesn’t block traffic. The policy adds `skip_detection` to the reason
header so the coverage gap is visible.

Model Armor scans only the first 40 URLs in each interaction for malicious URL detection.

### SDP De-identification

By default, an SDP match rejects the content. To redact sensitive data instead, enable **De-identify
Request** or **De-identify Response** and reference a Model Armor template that uses advanced SDP
with a de-identify template.

The policy rejects the content instead of redacting it when:

- The template doesn’t return de-identified text, for example, because it has no de-identify
  template.

- A filter other than SDP also matched.

- The scanned text spans more than one message or content part, so the policy can’t write the
  de-identified text back to a single field. For example, a multi-turn conversation scanned with the
  default **History Depth** of `0`, or a multimodal message with several content parts.

- The response is a stream. The policy can’t write the de-identified text back into a stream.

## Example Configurations

The following examples demonstrate common configuration patterns for the Google Model Armor
Guardrails policy.

### Minimal Configuration: Both Phases, One Template

`moderateRequest` and `moderateResponse` default to `true`, so both the prompt and the completion
are scanned against the same template, and the policy fails closed with a 5000 ms timeout.

```yaml
- policyRef:
    name: google-model-armor-guardrails-policy-v1-0-impl
    namespace: default
  config:
    modelArmorEndpoint: https://modelarmor.europe-west2.rep.googleapis.com
    tokenEndpoint: https://oauth2.googleapis.com
    serviceAccountKey: "${GOOGLE_MODEL_ARMOR_SA_KEY}"
    project: my-security-project
    location: europe-west2
    template: prod-guardrail
```

### Separate Request and Response Templates

A prompt-injection-focused template for the request phase and a data-leakage-focused template for
the response phase.

```yaml
- policyRef:
    name: google-model-armor-guardrails-policy-v1-0-impl
    namespace: default
  config:
    modelArmorEndpoint: https://modelarmor.us.rep.googleapis.com
    tokenEndpoint: https://oauth2.googleapis.com
    serviceAccountKey: "${GOOGLE_MODEL_ARMOR_SA_KEY}"
    project: my-security-project
    location: us
    template: shared-baseline
    advancedConfiguration:
      requestTemplate: injection-strict-input
      responseTemplate: leakage-strict-output
      apiTimeoutMs: 8000
```

### SDP De-identification

On an SDP match, sensitive data is redacted in place and traffic continues. Matches on other filters
are still rejected.

```yaml
- policyRef:
    name: google-model-armor-guardrails-policy-v1-0-impl
    namespace: default
  config:
    modelArmorEndpoint: https://modelarmor.us-central1.rep.googleapis.com
    tokenEndpoint: https://oauth2.googleapis.com
    serviceAccountKey: "${GOOGLE_MODEL_ARMOR_SA_KEY}"
    project: my-security-project
    location: us-central1
    template: sdp-deidentify-guardrail
    advancedConfiguration:
      deidentifyRequest: true
      deidentifyResponse: true
      historyDepth: 1
      enableMultiLanguageDetection: true
```

`historyDepth: 1` limits the request scan to the last message so that the de-identified text can be
written back to the request.

### Inspect Only, Fail Open

No traffic is ever rejected. Matched filters surface in the reason header, and if Model Armor is
unreachable, traffic proceeds unscanned. Use this to measure the impact of a template before
enforcing it.

```yaml
- policyRef:
    name: google-model-armor-guardrails-policy-v1-0-impl
    namespace: default
  config:
    modelArmorEndpoint: https://modelarmor.us-central1.rep.googleapis.com
    tokenEndpoint: https://oauth2.googleapis.com
    serviceAccountKey: "${GOOGLE_MODEL_ARMOR_SA_KEY}"
    project: my-security-project
    location: us-central1
    template: prod-guardrail
    advancedConfiguration:
      inspectOnly: true
      failOpen: true
```

## See Also

- [Google Cloud Model Armor documentation](https://cloud.google.com/security-command-center/docs/model-armor-overview)

- [Azure Content Safety Policy](https://docs.mulesoft.com/gateway/latest/policies-included-azure-content-safety)

- [Amazon Bedrock Guardrails Policy](https://docs.mulesoft.com/gateway/latest/policies-included-bedrock-guardrails)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies)

<!-- document id=72792784eee68b99640f943d83a6eb6a02d129b483c521866a175697d3b380a6 url=/mulesoft/current/en-us/gateway/latest/policies-included-graphql-access-control.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: graphql, access control, authorization, cedar, api gateway, flex gateway, gateway, policy
---

# GraphQL Access Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Access Control</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Authorizes incoming GraphQL requests by evaluating Cedar rules</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.14.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-access-control-release-notes">GraphQL Access Control</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>403 Forbidden — No rule authorizes the request. The response body is a JSON object with an <code>error</code> message such as <code>GraphQL request denied by access control policy</code>.</p></td></tr></tbody></table>

## Summary

The GraphQL Access Control policy authorizes each incoming GraphQL request against a set of
[Cedar](https://www.cedarpolicy.com/) rules that you define. Cedar is an open-source policy language
that expresses authorization as `permit` and `forbid` statements. Omni Gateway allows a request only
when at least one `permit` rule matches it and no `forbid` rule matches.

Use this policy to enforce fine-grained, attribute-based authorization on GraphQL traffic. For
example, you can restrict mutations to privileged clients, allow specific named operations, or gate
access by request header, SLA tier, or source IP address.

To make identity-based decisions, apply an upstream authentication policy, such as Basic
Authentication, Client ID Enforcement, JWT Validation, OAuth 2.0 Token Introspection, or OpenID
Connect, before this policy. The authentication policy populates the `principal` that the rules
evaluate. When no authentication policy runs, Omni Gateway evaluates the request against the
`Client::"None"` principal. For the attributes that each authentication policy provides, see
[Attributes Available to Cedar Rules](#attributes-available-to-cedar-rules).

After Omni Gateway extracts the GraphQL operation text, the policy evaluates your rules against the
request. The policy skips persisted queries and passes them to the upstream service without
authorization checks, because Omni Gateway doesn’t inspect their operation text. Non-GraphQL
requests also pass through.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-access-control-flex config: rules: <array> // REQUIRED, list of Cedar
policy statements; can't be empty

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>A list of Cedar policy statements that authorize requests. Each statement must be a valid Cedar <code>permit</code> or <code>forbid</code> rule that ends with a semicolon. The list can’t be empty.</p></div></div></td></tr></tbody></table>

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>The list of Cedar policy statements that authorize requests. Add one entry per <code>permit</code> or <code>forbid</code> rule. Each rule must be valid Cedar and end with a semicolon.</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

## Attributes Available to Cedar Rules

Cedar rules authorize a request by matching against attributes of the `principal`, which is the
authenticated client, and the request `context`. Use these attributes in the `when` clause of a rule
to make fine-grained decisions.

Cedar rules can match requests against these `context` attributes:

<table><colgroup><col> <col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>context.headers["&lt;name&gt;"]</code></p></div></div></td><td><div><div><p>The value of a request header. Use bracket notation to access header names that contain characters such as dashes, for example, <code>context.headers["x-internal"]</code>.</p></div></div></td></tr><tr><td><div><div><p><code>context.graphqlQuery</code></p></div></div></td><td><div><div><p>The raw GraphQL operation text.</p></div></div></td></tr><tr><td><div><div><p><code>context.operationName</code></p></div></div></td><td><div><div><p>The name of the resolved operation. If the request provides an <code>operationName</code>, Omni Gateway resolves that operation. Otherwise, Omni Gateway resolves the first operation in the document. Empty when the operation is anonymous.</p></div></div></td></tr><tr><td><div><div><p><code>context.operationType</code></p></div></div></td><td><div><div><p>The type of the resolved operation: <code>query</code>, <code>mutation</code>, or <code>subscription</code>. Shorthand documents resolve to <code>query</code>.</p></div></div></td></tr><tr><td><div><div><p><code>context.rootField</code></p></div></div></td><td><div><div><p>The name of the first top-level field in the resolved operation.</p></div></div></td></tr><tr><td><div><div><p><code>context.ipAddress</code></p></div></div></td><td><div><div><p>The source IP address of the request, when available.</p></div></div></td></tr></tbody></table>

Cedar rules can also match requests against these `principal` attributes. You must apply an
authentication policy before the GraphQL Access Control policy to populate these values. To learn
what policies update which attributes, see
[Authentication Policies Principal Attributes](#authentication-policies-principal-attributes).

<table><colgroup><col> <col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>principal.principal</code></p></div></div></td><td><div><div><p>The authenticated principal identifier, such as the Basic Authentication username or the raw token.</p></div></div></td></tr><tr><td><div><div><p><code>principal.client_id</code></p></div></div></td><td><div><div><p>The client ID resolved by the upstream authentication policy, when available.</p></div></div></td></tr><tr><td><div><div><p><code>principal.client_name</code></p></div></div></td><td><div><div><p>The client application name resolved by the upstream authentication policy, when available.</p></div></div></td></tr><tr><td><div><div><p><code>principal.properties.&lt;name&gt;</code></p></div></div></td><td><div><div><p>Additional properties published by the upstream authentication policy. For example, JWT Validation exposes <code>principal.properties.claims.&lt;claim&gt;</code>, and OAuth 2.0 Token Introspection exposes <code>principal.properties.scope</code>.</p></div></div></td></tr><tr><td><div><div><p><code>principal.properties.slaId</code></p></div></div></td><td><div><div><p>The SLA tier ID of the client, when an upstream policy publishes it.</p></div></div></td></tr><tr><td><div><div><p><code>principal.properties.slaName</code></p></div></div></td><td><div><div><p>The human-readable SLA tier name that corresponds to <code>slaId</code>, resolved from the API instance metadata.</p></div></div></td></tr></tbody></table>

When no authentication policy runs, Omni Gateway evaluates the request against the `Client::"None"`
principal, and these `principal` attributes are empty.

## Authentication Policies Principal Attributes

Apply an authentication policy before this policy to populate the `principal` attributes that your
Cedar rules evaluate.

### Included Authentication Policies

The authentication policy you apply affects the available Cedar `principal` bindings:

- Multiple policies can validate Client ID:

  - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-client-id-enforcement)

  - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting-sla)

  - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-oauth-token-introspection) (If Client
    ID enforcement is configured)

  - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-openid-token-enforcement)
    (If Client ID enforcement is configured)

  - [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation) (If Client ID enforcement is
    configured)

    Policies validating Client ID provide these Cedar bindings:

  - `principal.client_name`: Name of the contract’s client application

  - `principal.principal`: ID of the contract’s client application

  - `principal.properties.slaId`: SLA ID assigned to the contract

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation):

  - `principal.properties.claims.<claimName>`: All claims provided by the JWT

- Multiple policies validate basic authentication credentials:

  - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple)

  - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-ldap)

    Policies validating basic authentication credentials provide these Cedar bindings:

  - `principal.principal`: Username passed as basic auth user

### Custom Authentication Policies

For custom authentication policies, the custom policy must authenticate by using the
`Authentication` injectable. To configure the `Authentication` injectable, see
[Accessing Request Authentication Information](https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features-authentication).

For the Rust `AuthenticationData` structure:

```rust
pub struct AuthenticationData {
    pub principal: Option<String>,
    pub client_id: Option<String>,
    pub client_name: Option<String>,
    pub properties: Value,
}
```

The `AuthenticationData` parameters map to these Cedar bindings:

- `principal`: `principal.principal`

- `client_name`: `principal.client_name`

- `properties`: `principal.properties.*`

## Configuration Examples

These examples are valid whether you configure the policy in a Local Mode resource file or through
the Omni Gateway UI.

This example permits queries from any client but restricts mutations to clients that authenticate as
`admin`:

```yaml
- policyRef:
    name: graphql-access-control-flex
  config:
    rules:
      - permit(principal, action, resource) when { context.operationType == "query" };
      - permit(principal, action, resource) when { principal.principal == "admin" };
```

This example permits requests only from internal callers that a request header identifies, and
blocks introspection-style queries against the `__schema` root field:

```yaml
- policyRef:
    name: graphql-access-control-flex
  config:
    rules:
      - permit(principal, action, resource) when { context.headers["x-internal"] == "true" };
      - forbid(principal, action, resource) when { context.rootField == "__schema" };
```

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

- [GraphQL Introspection Control Policy](https://docs.mulesoft.com/gateway/latest/policies-included-graphql-introspection-control)

- [GraphQL Schema Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-graphql-schema-validation)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/latest/gateway-secure-apis)

- [Cedar policy language](https://www.cedarpolicy.com/)

<!-- document id=1f16aaf7e30a574e17840c923f29b02b1cd9e0061563d9bfbf1ad6e6d301af41 url=/mulesoft/current/en-us/gateway/1.13/policies-included-graphql-introspection-control.md -->

# GraphQL Introspection Control Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL Introspection Control</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks or allows requests that  access the <code><em>schema</em></code><em>, <code></code></em><code>type</code>, and <code>__typename</code> GraphQL meta fields</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.13.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-introspection-control-release-notes" class="xref page">GraphQL Introspection Control</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned status codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">403 Forbidden — The response follows the standard GraphQL error format, including a message such as <code>Introspection field '__schema' is not allowed</code>.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

GraphQL servers include built-in introspection fields that allow clients to discover your API’s types and structure. Configure The GraphQL Introspection Control policy inspects incoming operations blocks requests that reference restricted fields.

Use the introspection policy to block requests to a combination of these fields:

- `__schema`, used to discover the full API schema.
- `__type`, used to look up details for a specific type by name.
- `__typename`, used to read the concrete type name of an object.

Blocking `__typename` can affect GraphQL client libraries that rely on it for result caching.

After Omni Gateway resolves the GraphQL query, the policy evaluates the operation text. Omni Gateway doesn’t inspect the operation text for persisted queries and passes them through without introspection checks.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

\- policyRef:
    name: graphql-introspection-control-flex
  config:
    blockSchema: <boolean> // OPTIONAL, default: false
    blockType: <boolean> // OPTIONAL, default: false
    blockTypename: <boolean> // OPTIONAL, default: false

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>blockSchema</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If <code>true</code>, Omni Gateway blocks queries that use the <code>__schema</code> field for full schema discovery.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>blockType</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If <code>true</code>, Omni Gateway blocks queries that use the <code>__type</code> field to look up a type by name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>blockTypename</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If <code>true</code>, Omni Gateway blocks queries that use the <code>__typename</code> field to read an object’s concrete type name.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

This example blocks schema and type introspection, but allows the use `__typename`:

```yaml
- policyRef:
    name: graphql-introspection-control-flex
  config:
    blockSchema: true
    blockType: true
    blockTypename: false
```

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><strong>Block</strong> <code>__schema</code> (<code>blockSchema</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If enabled, Omni Gateway blocks queries that use the <code>__schema</code> field for full schema discovery.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><strong>Block</strong> <code>__type</code> (<code>blockType</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If enabled, Omni Gateway blocks queries that use the <code>__type</code> field to look up a type by name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><strong>Block</strong> <code>__typename</code> (<code>blockTypename</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If enabled, Omni Gateway blocks queries that use the <code>__typename</code> field to read an object’s concrete type name.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=b26ad75868c4f96916493aa26c49a91059f6e925a80715b73f4727866fbf7f16 url=/mulesoft/current/en-us/gateway/latest/policies-included-graphql-introspection-control.md -->

# GraphQL Introspection Control Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL Introspection Control</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks or allows requests that  access the <code><em>schema</em></code><em>, <code></code></em><code>type</code>, and <code>__typename</code> GraphQL meta fields</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.13.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-introspection-control-release-notes" class="xref page">GraphQL Introspection Control</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned status codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">403 Forbidden — The response follows the standard GraphQL error format, including a message such as <code>Introspection field '__schema' is not allowed</code>.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

GraphQL servers include built-in introspection fields that allow clients to discover your API’s types and structure. Configure The GraphQL Introspection Control policy inspects incoming operations blocks requests that reference restricted fields.

Use the introspection policy to block requests to a combination of these fields:

- `__schema`, used to discover the full API schema.
- `__type`, used to look up details for a specific type by name.
- `__typename`, used to read the concrete type name of an object.

Blocking `__typename` can affect GraphQL client libraries that rely on it for result caching.

After Omni Gateway resolves the GraphQL query, the policy evaluates the operation text. Omni Gateway doesn’t inspect the operation text for persisted queries and passes them through without introspection checks.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

\- policyRef:
    name: graphql-introspection-control-flex
  config:
    blockSchema: <boolean> // OPTIONAL, default: false
    blockType: <boolean> // OPTIONAL, default: false
    blockTypename: <boolean> // OPTIONAL, default: false

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>blockSchema</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If <code>true</code>, Omni Gateway blocks queries that use the <code>__schema</code> field for full schema discovery.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>blockType</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If <code>true</code>, Omni Gateway blocks queries that use the <code>__type</code> field to look up a type by name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>blockTypename</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If <code>true</code>, Omni Gateway blocks queries that use the <code>__typename</code> field to read an object’s concrete type name.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

This example blocks schema and type introspection, but allows the use `__typename`:

```yaml
- policyRef:
    name: graphql-introspection-control-flex
  config:
    blockSchema: true
    blockType: true
    blockTypename: false
```

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><strong>Block</strong> <code>__schema</code> (<code>blockSchema</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If enabled, Omni Gateway blocks queries that use the <code>__schema</code> field for full schema discovery.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><strong>Block</strong> <code>__type</code> (<code>blockType</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If enabled, Omni Gateway blocks queries that use the <code>__type</code> field to look up a type by name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><strong>Block</strong> <code>__typename</code> (<code>blockTypename</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>If enabled, Omni Gateway blocks queries that use the <code>__typename</code> field to read an object’s concrete type name.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=4139d8fd62bc89adfba939e8247f10ccc0867fe0c266cf9a32f7663354a3876b url=/mulesoft/current/en-us/gateway/1.13/policies-included-graphql-operation-limits.md -->

---
product: Omni Gateway
version: 1.13
keywords: graphql, operation limits, api gateway, flex gateway, gateway, policy
---

# GraphQL Operation Limits Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Operation Limits</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Limits GraphQL operation depth, aliases, root fields, and directives</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-operation-limits-release-notes">GraphQL Operation Limits</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>400 - Operations that exceed a configured limit. The response follows the standard GraphQL error format and lists each violation. For example, <code>Query depth of 7 exceeds the maximum allowed depth of 5</code></p></td></tr></tbody></table>

## Summary

The GraphQL Operation Limits policy restricts the depth, aliases, root fields, and directives in
incoming requests. If an operation exceeds a limit, Omni Gateway returns a 400 error with a JSON
`errors` array detailing each violation.

Omni Gateway evaluates limits at parse time from the document text. Because fragment spreads don’t
expand, metrics reflect the written document instead of a fully expanded query plan that the gateway
builds at runtime.

For persisted queries, the gateway resolves the document without inline query text. The policy
bypasses these requests and allows them to pass to the upstream service.

If the parser can’t read the query, the policy logs a debug message and doesn’t block the request,
so upstream validation or other policies can still run.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-operation-limits-flex config: maxDepth: <integer> // OPTIONAL, use -1 or
omit to disable maxAliases: <integer> // OPTIONAL, use -1 or omit to disable maxRootFields:
<integer> // OPTIONAL, use -1 or omit to disable maxDirectives: <integer> // OPTIONAL, use -1 or
omit to disable

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxDepth</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum depth of nested fields in a single document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAliases</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum number of field aliases.</p></div></div></td></tr><tr><td><div><div><p><code>maxRootFields</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum number of top-level fields.</p></div></div></td></tr><tr><td><div><div><p><code>maxDirectives</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum number of directives across the document.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example caps depth and aliases while leaving root fields and directives unrestricted.

```yaml
- policyRef:
    name: graphql-operation-limits-flex
  config:
    maxDepth: 8
    maxAliases: 20
    maxRootFields: -1
    maxDirectives: -1
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Maximum Depth</p></div></div></td><td><div><div><p>Deepest level of field nesting in a document. For example, <code>{ hero { name } }</code> has a depth of 2.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Maximum Aliases</p></div></div></td><td><div><div><p>Maximum number of field aliases in the document.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Maximum Root Fields</p></div></div></td><td><div><div><p>Maximum number of top-level fields that an operation can declare.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Maximum Directives</p></div></div></td><td><div><div><p>Maximum number of directives across the document.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/1.13/gateway-secure-apis)

<!-- document id=c874a6e9ea383c069d833c9a4b238c407fe24c9bf30a30f90dda60d47e86c858 url=/mulesoft/current/en-us/gateway/latest/policies-included-graphql-operation-limits.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: graphql, operation limits, api gateway, flex gateway, gateway, policy
---

# GraphQL Operation Limits Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Operation Limits</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Limits GraphQL operation depth, aliases, root fields, and directives</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-operation-limits-release-notes">GraphQL Operation Limits</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>400 - Operations that exceed a configured limit. The response follows the standard GraphQL error format and lists each violation. For example, <code>Query depth of 7 exceeds the maximum allowed depth of 5</code></p></td></tr></tbody></table>

## Summary

The GraphQL Operation Limits policy restricts the depth, aliases, root fields, and directives in
incoming requests. If an operation exceeds a limit, Omni Gateway returns a 400 error with a JSON
`errors` array detailing each violation.

Omni Gateway evaluates limits at parse time from the document text. Because fragment spreads don’t
expand, metrics reflect the written document instead of a fully expanded query plan that the gateway
builds at runtime.

For persisted queries, the gateway resolves the document without inline query text. The policy
bypasses these requests and allows them to pass to the upstream service.

If the parser can’t read the query, the policy logs a debug message and doesn’t block the request,
so upstream validation or other policies can still run.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-operation-limits-flex config: maxDepth: <integer> // OPTIONAL, use -1 or
omit to disable maxAliases: <integer> // OPTIONAL, use -1 or omit to disable maxRootFields:
<integer> // OPTIONAL, use -1 or omit to disable maxDirectives: <integer> // OPTIONAL, use -1 or
omit to disable

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxDepth</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum depth of nested fields in a single document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAliases</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum number of field aliases.</p></div></div></td></tr><tr><td><div><div><p><code>maxRootFields</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum number of top-level fields.</p></div></div></td></tr><tr><td><div><div><p><code>maxDirectives</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Omit or set to <code>-1</code> to disable</p></div></div></td><td><div><div><p>Maximum number of directives across the document.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example caps depth and aliases while leaving root fields and directives unrestricted.

```yaml
- policyRef:
    name: graphql-operation-limits-flex
  config:
    maxDepth: 8
    maxAliases: 20
    maxRootFields: -1
    maxDirectives: -1
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Maximum Depth</p></div></div></td><td><div><div><p>Deepest level of field nesting in a document. For example, <code>{ hero { name } }</code> has a depth of 2.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Maximum Aliases</p></div></div></td><td><div><div><p>Maximum number of field aliases in the document.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Maximum Root Fields</p></div></div></td><td><div><div><p>Maximum number of top-level fields that an operation can declare.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Maximum Directives</p></div></div></td><td><div><div><p>Maximum number of directives across the document.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/latest/gateway-secure-apis)

<!-- document id=a03d6b9dddd2509d04f4c8cb20bf22d3b625e5b48dc58abb38680c403de51216 url=/mulesoft/current/en-us/gateway/1.13/policies-included-graphql-schema-validation.md -->

---
product: Omni Gateway
version: 1.13
keywords: graphql, schema validation, api gateway, flex gateway, gateway, policy
---

# GraphQL Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming GraphQL operations against a GraphQL schema definition</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-schema-validation-release-notes">GraphQL Schema Validation</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>400 - The operation doesn’t satisfy the schema. When <strong>Block request</strong> is enabled, the JSON response includes GraphQL-style <code>errors</code> with a validation message.</p></td></tr></tbody></table>

## Summary

The GraphQL Schema Validation policy applies standard GraphQL validation rules, including field and
argument correctness, fragments, directives, unions, interfaces, and other specification rules.

The policy loads the schema in these ways:

- If `source` is `context`, Flex Gateway automatically loads the schema file from the API asset in
  Anypoint Exchange.

- If `source` is `inline`, provide the schema text directly in the policy configuration. This is
  required for local mode or environments not connected to Exchange.

If the document includes an `@link` to the Apollo Federation specification URL, Omni Gateway uses
this schema to validate all incoming requests.

After Omni Gateway extracts inline GraphQL operation text from the request, the policy runs
validation. If Omni Gateway can’t resolve normal operation text, such as persisted query flows, it
skips these checks and logs a warning before it forwards the request to the upstream.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-schema-validation-flex config: source: <string> // OPTIONAL, default:
context; values: "context" or "inline" schema: <string> // REQUIRED when source is inline; omit when
source is context blockOperation: <boolean> // OPTIONAL, default: true

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p>Where Omni Gateway retrieves the schema for validation. If set to <code>context</code>, Omni Gateway automatically loads the schema file from the API asset in Anypoint Exchange. If set to <code>inline</code>, provide the schema text directly in the policy configuration. This is required for local mode or environments not connected to Exchange.</p></div></div></td></tr><tr><td><div><div><p><code>schema</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>The schema text used for validation. Required when <code>source</code> is set to <code>inline</code>.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>How Omni Gateway handles requests that fail validation. If <code>true</code>, Omni Gateway blocks the request and returns a <code>400</code> Bad Request. If <code>false</code>, Omni Gateway logs a warning and forwards the request to your backend.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example validates against a minimal inline schema:

```yaml
- policyRef:
    name: graphql-schema-validation-flex
  config:
    source: inline
    blockOperation: true
    schema: |
      type Query {
        hello: String
      }
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>If enabled and the operation doesn’t conform to the schema, Omni Gateway returns a <code>400</code> error. If disabled, Omni Gateway logs a warning and forwards the request.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

- [Schema Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-schema-validation)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/1.13/gateway-secure-apis)

<!-- document id=e7020996952a575e3f637efa691010694ffca9b6d2893c7892d0badd9d0890da url=/mulesoft/current/en-us/gateway/latest/policies-included-graphql-schema-validation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: graphql, schema validation, api gateway, flex gateway, gateway, policy
---

# GraphQL Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming GraphQL operations against a GraphQL schema definition</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-schema-validation-release-notes">GraphQL Schema Validation</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>400 - The operation doesn’t satisfy the schema. When <strong>Block request</strong> is enabled, the JSON response includes GraphQL-style <code>errors</code> with a validation message.</p></td></tr></tbody></table>

## Summary

The GraphQL Schema Validation policy applies standard GraphQL validation rules, including field and
argument correctness, fragments, directives, unions, interfaces, and other specification rules.

The policy loads the schema in these ways:

- If `source` is `context`, Flex Gateway automatically loads the schema file from the API asset in
  Anypoint Exchange.

- If `source` is `inline`, provide the schema text directly in the policy configuration. This is
  required for local mode or environments not connected to Exchange.

If the document includes an `@link` to the Apollo Federation specification URL, Omni Gateway uses
this schema to validate all incoming requests.

After Omni Gateway extracts inline GraphQL operation text from the request, the policy runs
validation. If Omni Gateway can’t resolve normal operation text, such as persisted query flows, it
skips these checks and logs a warning before it forwards the request to the upstream.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-schema-validation-flex config: source: <string> // OPTIONAL, default:
context; values: "context" or "inline" schema: <string> // REQUIRED when source is inline; omit when
source is context blockOperation: <boolean> // OPTIONAL, default: true

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p>Where Omni Gateway retrieves the schema for validation. If set to <code>context</code>, Omni Gateway automatically loads the schema file from the API asset in Anypoint Exchange. If set to <code>inline</code>, provide the schema text directly in the policy configuration. This is required for local mode or environments not connected to Exchange.</p></div></div></td></tr><tr><td><div><div><p><code>schema</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>The schema text used for validation. Required when <code>source</code> is set to <code>inline</code>.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>How Omni Gateway handles requests that fail validation. If <code>true</code>, Omni Gateway blocks the request and returns a <code>400</code> Bad Request. If <code>false</code>, Omni Gateway logs a warning and forwards the request to your backend.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example validates against a minimal inline schema:

```yaml
- policyRef:
    name: graphql-schema-validation-flex
  config:
    source: inline
    blockOperation: true
    schema: |
      type Query {
        hello: String
      }
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>If enabled and the operation doesn’t conform to the schema, Omni Gateway returns a <code>400</code> error. If disabled, Omni Gateway logs a warning and forwards the request.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

- [Schema Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-schema-validation)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/latest/gateway-secure-apis)

<!-- document id=35a69417712a79453ac659323367c03e31f653263c3620b40919c87ea743080b url=/mulesoft/current/en-us/gateway/1.13/policies-included-graphql-static-query-complexity.md -->

---
product: Omni Gateway
version: 1.13
keywords: graphql, query complexity, api gateway, flex gateway, gateway, policy
---

# GraphQL Static Query Complexity Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Static Query Complexity</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Calculates query complexity and blocks requests that exceed the defined budget</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-static-query-complexity-release-notes">GraphQL Static Query Complexity</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>400 - Parse failures always trigger a 400 response. Complexity and list violations return this code only if <strong>Block request</strong> is enabled. The response includes a standard GraphQL errors object.</p></td></tr></tbody></table>

## Summary

The GraphQL Static Query Complexity policy estimates the complexity of each incoming GraphQL
operation from your GraphQL schema and the operation text. If the estimate exceeds the configured
budget or fails other checks enforced by the policy, Omni Gateway rejects the request or logs a
warning and forwards it upstream.

The policy loads schema in these ways:

- If `source` is `context`, Omni Gateway automatically loads the schema file from the API asset in
  Anypoint Exchange.

- If `source` is `inline`, provide the schema text directly in the policy configuration. This is
  required for local mode or environments not connected to Exchange.

After Omni Gateway extracts the GraphQL operation text, the policy analyzes query complexity.

If Omni Gateway can’t resolve the full operation text, as with persisted queries, it skips
complexity analysis.

If a system error occurs during analysis, even if the schema loads into memory, Omni Gateway logs a
warning and forwards the request instead of blocking it.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-static-query-complexity-flex config: maximumComplexity: <number> //
REQUIRED, must be positive source: <string> // OPTIONAL, default: context; values: "context" or
"inline" schema: <string> // REQUIRED when source is inline; omit when source is context
defaultFieldCost: <number> // OPTIONAL, default: 1.0, must be >= 0 blockOperation: <boolean> //
OPTIONAL, default: true rejectUnboundedLists: <boolean> // OPTIONAL, default: true directiveName:
<string> // OPTIONAL, default: cost valueArgument: <string> // OPTIONAL, default: weight
multipliersArgument: <string> // OPTIONAL, default: multipliers

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumComplexity</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>The maximum complexity score allowed for a single query. Requests exceeding this value are blocked or logged as warnings.</p></div></div></td></tr><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p><code>context</code> automatically retrieves the schema file from the API asset in Anypoint Exchange. <code>inline</code> uses the schema text provided directly in the policy configuration. This is required for local mode or environments not connected to Exchange.</p></div></div></td></tr><tr><td><div><div><p><code>schema</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>The schema text used for validation. Required if <code>source</code> is <code>inline</code>. Omit for <code>context</code></p></div></div></td></tr><tr><td><div><div><p><code>defaultFieldCost</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>1.0</code></p></div></div></td><td><div><div><p>The cost applied to fields that don’t have a specific complexity tag (typically @cost) in your schema file.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If <code>true</code>, Omni Gateway blocks the request and returns a <code>400</code> Bad Request error. If <code>false</code>, Omni Gateway logs a warning and forwards the request to your backend. Parse failures always trigger a <code>400</code> response, even if this setting is <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rejectUnboundedLists</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>If <code>true</code>, Omni Gateway blocks queries for list fields that lack a limiting argument, such as <code>first</code> or <code>limit</code>. This prevents users from requesting large datasets.</p></div></div></td></tr><tr><td><div><div><p><code>directiveName</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>cost</code></p></div></div></td><td><div><div><p>The name of the complexity tag in your schema file that defines per-field costs.</p></div></div></td></tr><tr><td><div><div><p><code>valueArgument</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>weight</code></p></div></div></td><td><div><div><p>The specific argument within your shema tag that defines the cost of a field. For example, in <code>@cost(value: 5)</code>, the argument is <code>value</code>.</p></div></div></td></tr><tr><td><div><div><p><code>multipliersArgument</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>multipliers</code></p></div></div></td><td><div><div><p>The argument in your shcema tag that lists which field arguments multiply the cost. For example, in <code>@cost(multipliers: ["first"])</code>, the value of the <code>first</code> argument is used to multiply the field’s cost.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example sets the maximum complexity at `250`, uses default costs and tag names, and provides
the schema text inline:

```yaml
- policyRef:
    name: graphql-static-query-complexity-flex
  config:
    source: inline
    maximumComplexity: 250
    blockOperation: true
    rejectUnboundedLists: true
    schema: |
      directive @cost(weight: Int!, multipliers: [String!]) on FIELD_DEFINITION

      type Query {
        users(limit: Int): [User!]! @cost(weight: 1, multipliers: ["limit"])
        version: String!
      }

      type User {
        id: ID!
        name: String!
      }
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Maximum Complexity</p></div></div></td><td><div><div><p>The maximum allowed complexity score for a query.</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default Field Cost</p></div></div></td><td><div><div><p>The cost applied to fields lacking a specific complexity tag in your schema file.</p></div></div></td><td><div><div><p><code>1.0</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If enabled, Omni Gateway blocks the request and returns a <code>400</code> error. If disabled, Omni Gateway logs violations as warnings. Parse failures always trigger a <code>400</code> response, regardless of this setting.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Reject unbounded lists</p></div></div></td><td><div><div><p>If enabled, Omni Gateway blocks queries for list fields that lack a limiting argument, such as <code>first</code> or <code>limit</code>.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Directive Name</p></div></div></td><td><div><div><p>The name of the complexity tag in your schema file that defines per-field costs.</p></div></div></td><td><div><div><p><code>cost</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Value Argument</p></div></div></td><td><div><div><p>The argument within your complexity tag that specifies the field’s base cost.</p></div></div></td><td><div><div><p><code>weight</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Multipliers Argument</p></div></div></td><td><div><div><p>The argument within your complexity tag that identifies which query parameters multiply the cost. For example, in \@cost(weight: 1, multipliers: ["limit"])<code>, the multipliers argument is `multipliers</code>, and the <code>limit</code> value multiplies the base cost.</p></div></div></td><td><div><div><p><code>multipliers</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

- [GraphQL Schema Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-graphql-schema-validation)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/1.13/gateway-secure-apis)

<!-- document id=0ac2a04d33d4fce1feb930433096f2c1c9cab5457a11fc6d0854a9fadc90d75d url=/mulesoft/current/en-us/gateway/latest/policies-included-graphql-static-query-complexity.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: graphql, query complexity, api gateway, flex gateway, gateway, policy
---

# GraphQL Static Query Complexity Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Static Query Complexity</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Calculates query complexity and blocks requests that exceed the defined budget</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-static-query-complexity-release-notes">GraphQL Static Query Complexity</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>400 - Parse failures always trigger a 400 response. Complexity and list violations return this code only if <strong>Block request</strong> is enabled. The response includes a standard GraphQL errors object.</p></td></tr></tbody></table>

## Summary

The GraphQL Static Query Complexity policy estimates the complexity of each incoming GraphQL
operation from your GraphQL schema and the operation text. If the estimate exceeds the configured
budget or fails other checks enforced by the policy, Omni Gateway rejects the request or logs a
warning and forwards it upstream.

The policy loads schema in these ways:

- If `source` is `context`, Omni Gateway automatically loads the schema file from the API asset in
  Anypoint Exchange.

- If `source` is `inline`, provide the schema text directly in the policy configuration. This is
  required for local mode or environments not connected to Exchange.

After Omni Gateway extracts the GraphQL operation text, the policy analyzes query complexity.

If Omni Gateway can’t resolve the full operation text, as with persisted queries, it skips
complexity analysis.

If a system error occurs during analysis, even if the schema loads into memory, Omni Gateway logs a
warning and forwards the request instead of blocking it.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-static-query-complexity-flex config: maximumComplexity: <number> //
REQUIRED, must be positive source: <string> // OPTIONAL, default: context; values: "context" or
"inline" schema: <string> // REQUIRED when source is inline; omit when source is context
defaultFieldCost: <number> // OPTIONAL, default: 1.0, must be >= 0 blockOperation: <boolean> //
OPTIONAL, default: true rejectUnboundedLists: <boolean> // OPTIONAL, default: true directiveName:
<string> // OPTIONAL, default: cost valueArgument: <string> // OPTIONAL, default: weight
multipliersArgument: <string> // OPTIONAL, default: multipliers

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumComplexity</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>The maximum complexity score allowed for a single query. Requests exceeding this value are blocked or logged as warnings.</p></div></div></td></tr><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p><code>context</code> automatically retrieves the schema file from the API asset in Anypoint Exchange. <code>inline</code> uses the schema text provided directly in the policy configuration. This is required for local mode or environments not connected to Exchange.</p></div></div></td></tr><tr><td><div><div><p><code>schema</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>The schema text used for validation. Required if <code>source</code> is <code>inline</code>. Omit for <code>context</code></p></div></div></td></tr><tr><td><div><div><p><code>defaultFieldCost</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>1.0</code></p></div></div></td><td><div><div><p>The cost applied to fields that don’t have a specific complexity tag (typically @cost) in your schema file.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If <code>true</code>, Omni Gateway blocks the request and returns a <code>400</code> Bad Request error. If <code>false</code>, Omni Gateway logs a warning and forwards the request to your backend. Parse failures always trigger a <code>400</code> response, even if this setting is <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rejectUnboundedLists</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>If <code>true</code>, Omni Gateway blocks queries for list fields that lack a limiting argument, such as <code>first</code> or <code>limit</code>. This prevents users from requesting large datasets.</p></div></div></td></tr><tr><td><div><div><p><code>directiveName</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>cost</code></p></div></div></td><td><div><div><p>The name of the complexity tag in your schema file that defines per-field costs.</p></div></div></td></tr><tr><td><div><div><p><code>valueArgument</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>weight</code></p></div></div></td><td><div><div><p>The specific argument within your shema tag that defines the cost of a field. For example, in <code>@cost(value: 5)</code>, the argument is <code>value</code>.</p></div></div></td></tr><tr><td><div><div><p><code>multipliersArgument</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>multipliers</code></p></div></div></td><td><div><div><p>The argument in your shcema tag that lists which field arguments multiply the cost. For example, in <code>@cost(multipliers: ["first"])</code>, the value of the <code>first</code> argument is used to multiply the field’s cost.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example sets the maximum complexity at `250`, uses default costs and tag names, and provides
the schema text inline:

```yaml
- policyRef:
    name: graphql-static-query-complexity-flex
  config:
    source: inline
    maximumComplexity: 250
    blockOperation: true
    rejectUnboundedLists: true
    schema: |
      directive @cost(weight: Int!, multipliers: [String!]) on FIELD_DEFINITION

      type Query {
        users(limit: Int): [User!]! @cost(weight: 1, multipliers: ["limit"])
        version: String!
      }

      type User {
        id: ID!
        name: String!
      }
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Maximum Complexity</p></div></div></td><td><div><div><p>The maximum allowed complexity score for a query.</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default Field Cost</p></div></div></td><td><div><div><p>The cost applied to fields lacking a specific complexity tag in your schema file.</p></div></div></td><td><div><div><p><code>1.0</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If enabled, Omni Gateway blocks the request and returns a <code>400</code> error. If disabled, Omni Gateway logs violations as warnings. Parse failures always trigger a <code>400</code> response, regardless of this setting.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Reject unbounded lists</p></div></div></td><td><div><div><p>If enabled, Omni Gateway blocks queries for list fields that lack a limiting argument, such as <code>first</code> or <code>limit</code>.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Directive Name</p></div></div></td><td><div><div><p>The name of the complexity tag in your schema file that defines per-field costs.</p></div></div></td><td><div><div><p><code>cost</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Value Argument</p></div></div></td><td><div><div><p>The argument within your complexity tag that specifies the field’s base cost.</p></div></div></td><td><div><div><p><code>weight</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Multipliers Argument</p></div></div></td><td><div><div><p>The argument within your complexity tag that identifies which query parameters multiply the cost. For example, in \@cost(weight: 1, multipliers: ["limit"])<code>, the multipliers argument is `multipliers</code>, and the <code>limit</code> value multiplies the base cost.</p></div></div></td><td><div><div><p><code>multipliers</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

- [GraphQL Schema Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-graphql-schema-validation)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/latest/gateway-secure-apis)

<!-- document id=bd26050b8ee42282f17d48ec3e0427fd1b145b278da19c1b666a3f84d0667bac url=/mulesoft/current/en-us/gateway/1.12/policies-included-header-injection.md -->

---
product: Omni Gateway
version: 1.12
keywords: header injection, api gateway, flex gateway, gateway, policy
---

# Header Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds headers to a request or response.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Injection policy adds HTTP headers to the request or response of a message. When you
configure this policy for your API, you must specify an inbound and outbound map of the headers that
you want to add in the message processing in the form of a key-value pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/1.12/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value or name of the header. For example,
all headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

If the injected header already exists in the message attributes, the policy creates a new header
without overriding the value of the existing one.

> [!NOTE] Only certain headers are restricted to support multiple values, and they will be
> overwritten using configured values. These headers are: `access-control-allow-origin`,
> `content-type`, `content-length`, `transfer-encoding`.
>
> To overwrite any other existing message header, remove it before adding your header. See the
> [Header Removal](https://docs.mulesoft.com/gateway/1.12/policies-included-header-removal) policy.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: header-injection-flex config: inboundHeaders: <array> // OPTIONAL, default:
\[\] - key: <string> // REQUIRED value: <string> // REQUIRED outboundHeaders: <array> // OPTIONAL,
default: \[\] - key: <string> // REQUIRED value: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of header to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr></tbody></table>

> [!NOTE] `inboundHeaders` and `outboundHeaders` can not both be empty.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

#### Resource Configuration Example

In the following example, all the headers matching the configured `#[attributes.requestPath]`
expression are injected into the message.

\- policyRef: name: header-injection-flex config: inboundHeaders: - key: "new-inbound-header" value:
"#\[attributes.requestPath\]" outboundHeaders: - key: "new-outbound-header" value:
"#\[attributes.requestPath\]"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

> [!NOTE] Header keys should be compliance with
> [HTTP 1.1](https://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2) standard.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

<!-- document id=3df8dec4f2fc74db564e8f67eef92bb6478548db77602e07adbf182a63f59b2f url=/mulesoft/current/en-us/gateway/1.13/policies-included-header-injection.md -->

---
product: Omni Gateway
version: 1.13
keywords: header injection, api gateway, flex gateway, gateway, policy
---

# Header Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds headers to a request or response.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-injection-release-notes">Header Injection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Injection policy adds HTTP headers to the request or response of a message. When you
configure this policy for your API, you must specify an inbound and outbound map of the headers that
you want to add in the message processing in the form of a key-value pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/1.13/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value or name of the header. For example,
all headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

If the injected header already exists in the message attributes, the policy creates a new header
without overriding the value of the existing one.

> [!NOTE] Only certain headers are restricted to support multiple values, and they will be
> overwritten using configured values. These headers are: `access-control-allow-origin`,
> `content-type`, `content-length`, `transfer-encoding`.
>
> To overwrite any other existing message header, remove it before adding your header. See the
> [Header Removal](https://docs.mulesoft.com/gateway/1.13/policies-included-header-removal) policy.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: header-injection-flex config: inboundHeaders: <array> // OPTIONAL, default:
\[\] - key: <string> // REQUIRED value: <string> // REQUIRED outboundHeaders: <array> // OPTIONAL,
default: \[\] - key: <string> // REQUIRED value: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of header to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr></tbody></table>

> [!NOTE] `inboundHeaders` and `outboundHeaders` can not both be empty.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

#### Resource Configuration Example

In the following example, all the headers matching the configured `#[attributes.requestPath]`
expression are injected into the message.

\- policyRef: name: header-injection-flex config: inboundHeaders: - key: "new-inbound-header" value:
"#\[attributes.requestPath\]" outboundHeaders: - key: "new-outbound-header" value:
"#\[attributes.requestPath\]"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

> [!NOTE] Header keys should be compliance with
> [HTTP 1.1](https://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2) standard.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

<!-- document id=08bf41c55758118b0c73ae2eb37654d0a31e713ff5420d3f43707b69035f5b0e url=/mulesoft/current/en-us/gateway/1.9/policies-included-header-injection.md -->

---
product: Omni Gateway
version: 1.9
keywords: header injection, api gateway, flex gateway, gateway, policy
---

# Header Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds headers to a request or response.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Injection policy adds HTTP headers to the request or response of a message. When you
configure this policy for your API, you must specify an inbound and outbound map of the headers that
you want to add in the message processing in the form of a key-value pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/1.9/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value or name of the header. For example,
all headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

If the injected header already exists in the message attributes, the policy creates a new header
without overriding the value of the existing one.

> [!NOTE] Only certain headers are restricted to support multiple values, and they will be
> overwritten using configured values. These headers are: `access-control-allow-origin`,
> `content-type`, `content-length`, `transfer-encoding`.
>
> To overwrite any other existing message header, remove it before adding your header. See the
> [Header Removal](https://docs.mulesoft.com/gateway/1.9/policies-included-header-removal) policy.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: header-injection-flex config: inboundHeaders: <array> // OPTIONAL, default:
\[\] - key: <string> // REQUIRED value: <string> // REQUIRED outboundHeaders: <array> // OPTIONAL,
default: \[\] - key: <string> // REQUIRED value: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of header to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr></tbody></table>

> [!NOTE] `inboundHeaders` and `outboundHeaders` can not both be empty.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

#### Resource Configuration Example

In the following example, all the headers matching the configured `#[attributes.requestPath]`
expression are injected into the message.

\- policyRef: name: header-injection-flex config: inboundHeaders: - key: "new-inbound-header" value:
"#\[attributes.requestPath\]" outboundHeaders: - key: "new-outbound-header" value:
"#\[attributes.requestPath\]"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

> [!NOTE] Header keys should be compliance with
> [HTTP 1.1](https://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2) standard.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

<!-- document id=3132d968c7a9d50fb2b45fc95561d296b95fe107d3e093f914c28b83720c62e8 url=/mulesoft/current/en-us/gateway/latest/policies-included-header-injection.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: header injection, api gateway, flex gateway, gateway, policy
---

# Header Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds headers to a request or response.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-injection-release-notes">Header Injection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Injection policy adds HTTP headers to the request or response of a message. When you
configure this policy for your API, you must specify an inbound and outbound map of the headers that
you want to add in the message processing in the form of a key-value pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/latest/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value or name of the header. For example,
all headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

If the injected header already exists in the message attributes, the policy creates a new header
without overriding the value of the existing one.

> [!NOTE] Only certain headers are restricted to support multiple values, and they will be
> overwritten using configured values. These headers are: `access-control-allow-origin`,
> `content-type`, `content-length`, `transfer-encoding`.
>
> To overwrite any other existing message header, remove it before adding your header. See the
> [Header Removal](https://docs.mulesoft.com/gateway/latest/policies-included-header-removal) policy.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: header-injection-flex config: inboundHeaders: <array> // OPTIONAL, default:
\[\] - key: <string> // REQUIRED value: <string> // REQUIRED outboundHeaders: <array> // OPTIONAL,
default: \[\] - key: <string> // REQUIRED value: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>inboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of header to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.key</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header name</p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders.value</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A string or DataWeave expression for header value</p></div></div></td></tr></tbody></table>

> [!NOTE] `inboundHeaders` and `outboundHeaders` can not both be empty.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

#### Resource Configuration Example

In the following example, all the headers matching the configured `#[attributes.requestPath]`
expression are injected into the message.

\- policyRef: name: header-injection-flex config: inboundHeaders: - key: "new-inbound-header" value:
"#\[attributes.requestPath\]" outboundHeaders: - key: "new-outbound-header" value:
"#\[attributes.requestPath\]"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the beginning of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Inbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the beginning of the message.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of headers to be injected at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Key</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header name at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Outbound Header Value</p></div></div></td><td><div><div><p>String or Dataweave expression to be used as header value at the end of the message processing.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

> [!NOTE] Header keys should be compliance with
> [HTTP 1.1](https://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2) standard.

To use single quotes directly in a String value (for example
`"default-src 'none'; frame-ancestors 'none';"`), either:

- Use a DataWeave expression:

  #\["default-src 'none'; frame-ancestors 'none';"\]

- Use character escaping:

  "default-src \\'none\\'; frame-ancestors \\'none\\';"

<!-- document id=b887e3c83a4bae305237033c7ed7c1ec64089d341e5d6b554fc844fcc0450c27 url=/mulesoft/current/en-us/gateway/1.12/policies-included-header-removal.md -->

---
product: Omni Gateway
version: 1.12
keywords: header removal, api gateway, flex gateway, gateway, policy
---

# Header Removal Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Removal</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Removes headers from a request or a response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Removal policy removes all listed headers from a request or a response of a message when
you specify an inbound and outbound map of the headers that you want to remove with a key-value
pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/1.12/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value of the header. For example, all
headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

> [!NOTE] The following headers may not be removed: accept, host, content-type, content-length,
> date, transfer-encoding, connection,

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: header-removal-flex config: inboundHeaders: <array> // OPTIONAL, default: \[\]
outboundHeaders: <array> // OPTIONAL, default: \[\]

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div><div><div data-type="NOTE"><div><p><code>inboundHeaders</code> and <code>outboundHeaders</code> can not both be empty.</p></div></div></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: header-removal-flex config: inboundHeaders: - "Cache-Control" -
"Access-Control.\*" outboundHeaders: - "Access-Control-Allow-Credentials"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

## How This Policy Works

Because every header that matches a Header Removal policy parameter is removed from the message, you
must be careful about how you configure that parameter.

For example, the following parameter configuration removes any header starting with the word
`Access-Control`, such as the `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin`
headers from a message. The configuration also removes the `Cache-Control` header:

![Removed headers at the start of message processing](/mulesoft/current/en-us/gateway/1.12/_images/remove-inbound-header.png)

Figure 1. Inbound Header

<!-- document id=1e5d433667b18a20c030d0df423fb1b22d56c34ec51cdc5cb8a13209f77b457a url=/mulesoft/current/en-us/gateway/1.13/policies-included-header-removal.md -->

---
product: Omni Gateway
version: 1.13
keywords: header removal, api gateway, flex gateway, gateway, policy
---

# Header Removal Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Removal</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Removes headers from a request or a response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-removal-release-notes">Header Removal</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Removal policy removes all listed headers from a request or a response of a message when
you specify an inbound and outbound map of the headers that you want to remove with a key-value
pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/1.13/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value of the header. For example, all
headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

> [!NOTE] The following headers may not be removed: accept, host, content-type, content-length,
> date, transfer-encoding, connection,

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: header-removal-flex config: inboundHeaders: <array> // OPTIONAL, default: \[\]
outboundHeaders: <array> // OPTIONAL, default: \[\]

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div><div><div data-type="NOTE"><div><p><code>inboundHeaders</code> and <code>outboundHeaders</code> can not both be empty.</p></div></div></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: header-removal-flex config: inboundHeaders: - "Cache-Control" -
"Access-Control.\*" outboundHeaders: - "Access-Control-Allow-Credentials"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

## How This Policy Works

Because every header that matches a Header Removal policy parameter is removed from the message, you
must be careful about how you configure that parameter.

For example, the following parameter configuration removes any header starting with the word
`Access-Control`, such as the `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin`
headers from a message. The configuration also removes the `Cache-Control` header:

![Removed headers at the start of message processing](/mulesoft/current/en-us/gateway/1.13/_images/remove-inbound-header.png)

Figure 1. Inbound Header

<!-- document id=ac42a2c8c953254a360093cb5d54e0eba630c194af10eab813d709fc4fbc9bff url=/mulesoft/current/en-us/gateway/1.9/policies-included-header-removal.md -->

---
product: Omni Gateway
version: 1.9
keywords: header removal, api gateway, flex gateway, gateway, policy
---

# Header Removal Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Removal</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Removes headers from a request or a response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Removal policy removes all listed headers from a request or a response of a message when
you specify an inbound and outbound map of the headers that you want to remove with a key-value
pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/1.9/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value of the header. For example, all
headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

> [!NOTE] The following headers may not be removed: accept, host, content-type, content-length,
> date, transfer-encoding, connection,

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: header-removal-flex config: inboundHeaders: <array> // OPTIONAL, default: \[\]
outboundHeaders: <array> // OPTIONAL, default: \[\]

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div><div><div data-type="NOTE"><div><p><code>inboundHeaders</code> and <code>outboundHeaders</code> can not both be empty.</p></div></div></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: header-removal-flex config: inboundHeaders: - "Cache-Control" -
"Access-Control.\*" outboundHeaders: - "Access-Control-Allow-Credentials"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

## How This Policy Works

Because every header that matches a Header Removal policy parameter is removed from the message, you
must be careful about how you configure that parameter.

For example, the following parameter configuration removes any header starting with the word
`Access-Control`, such as the `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin`
headers from a message. The configuration also removes the `Cache-Control` header:

![Removed headers at the start of message processing](/mulesoft/current/en-us/gateway/1.9/_images/remove-inbound-header.png)

Figure 1. Inbound Header

<!-- document id=7a15339a96619990fa2a0d968d46721d54f86cf3b61b56f63cb02a66202fc2bd url=/mulesoft/current/en-us/gateway/latest/policies-included-header-removal.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: header removal, api gateway, flex gateway, gateway, policy
---

# Header Removal Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Header Removal</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Removes headers from a request or a response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-removal-release-notes">Header Removal</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>500 - The configuration includes an expression that was not evaluated.</p></td></tr></tbody></table>

## Summary

The Header Removal policy removes all listed headers from a request or a response of a message when
you specify an inbound and outbound map of the headers that you want to remove with a key-value
pair.

![A flow chart illustrating the process of setting header injection and removal policies for clients accessing an API through a proxy](/mulesoft/current/en-us/gateway/latest/_images/header-inject-remove-diagram.png)

You can optionally include DataWeave expressions in the value of the header. For example, all
headers matching the following configured expression are injected to the message:

`“#[attributes.requestPath]”`

> [!NOTE] The following headers may not be removed: accept, host, content-type, content-length,
> date, transfer-encoding, connection,

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: header-removal-flex config: inboundHeaders: <array> // OPTIONAL, default: \[\]
outboundHeaders: <array> // OPTIONAL, default: \[\]

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>inboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p><code>outboundHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Map of header names or regular expressions to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div><div><div data-type="NOTE"><div><p><code>inboundHeaders</code> and <code>outboundHeaders</code> can not both be empty.</p></div></div></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: header-removal-flex config: inboundHeaders: - "Cache-Control" -
"Access-Control.\*" outboundHeaders: - "Access-Control-Allow-Credentials"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>Inbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the beginning of the message processing, for example, <code>Cache-Control, Access-Control.*</code></p></div></div></td></tr><tr><td><div><div><p>Outbound Header Map</p></div></div></td><td><div><div><p>List of header names or regular expressions (comma separated) to be removed at the end of the message processing, for example, <code>Access-Control-Allow-Credentials</code></p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td></tr></tbody></table>

## How This Policy Works

Because every header that matches a Header Removal policy parameter is removed from the message, you
must be careful about how you configure that parameter.

For example, the following parameter configuration removes any header starting with the word
`Access-Control`, such as the `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin`
headers from a message. The configuration also removes the `Cache-Control` header:

![Removed headers at the start of message processing](/mulesoft/current/en-us/gateway/latest/_images/remove-inbound-header.png)

Figure 1. Inbound Header

<!-- document id=3da3fac75f23fa9968143056c4cc31ffcc4ada17a99e3c055edf7b8bdc54caf6 url=/mulesoft/current/en-us/gateway/1.12/policies-included-health-check.md -->

---
product: Omni Gateway
version: 1.12
keywords: health check, api gateway, flex gateway, gateway, policy
---

# Health Check Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Health Check</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Monitors API upstream health at specific intervals</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Health Check policy enables you to monitor an API instance’s connection to an upstream service
and sends you an email alert if the connection status changes. The Health Check policy monitors the
health of the upstream service and not the health of the API instance or Flex Gateway.

The Health Check policy monitors your API by making GET requests to the specified upstream’s base
path. You must specify a base path with a GET request. Requests are made at a fixed schedule every
minute with the first request. The first request occurs a minute after the policy is applied.
Requests made by the Health Check policy do not count as Flex Gateway API calls for pricing
purposes.

When you configure Health Check, specify a response code for the GET request that indicates a
healthy connection. For example, the status code of an active API should return 200, indicating the
API can receive connections. The platform sends an email alert when the status code is not 200.
Health Check only validates the response code, so what is returned to the endpoint is unimportant.

No logging event appears for healthy responses. Flex Gateway logs only unhealthy responses.

You can use any 1xx, 2xx, 3xx, 4xx, or 5xx response codes. However, if you expect successful
connections to your endpoints, 2xx response codes are ideal. Only a number response code is
accepted.

You are required to create an alert for the Health Check policy. Applying the policy navigates you
to the Create Alert page, where you must create an alert. For information about how to configure
your alert, visit [Using Flex Gateway API Alerts](https://docs.mulesoft.com/gateway/1.12/flex-use-api-alerts).

> [!IMPORTANT] Applying the Health Check policy to API Instances with an outbound TLS context also
> applied causes the Health Check policy to return an unhealthy connection.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The Health Check policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Upstream URL</p></div></div></td><td><div><div><p>The full URL of the API upstream you are monitoring</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Base path</p></div></div></td><td><div><div><p>The HTTP path of the GET method that is requested during health checks</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Response code</p></div></div></td><td><div><div><p>The expected status code of the GET request specified in the base path. Only a number response code is accepted.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=0ba79986fe9ccdc946b06a09c1aba45ffe37137bec181fd0b4c725b17c24de3c url=/mulesoft/current/en-us/gateway/1.13/policies-included-health-check.md -->

---
product: Omni Gateway
version: 1.13
keywords: health check, api gateway, flex gateway, gateway, policy
---

# Health Check Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Health Check</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Monitors API upstream health at specific intervals</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/health-check-release-notes">Health Check Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Health Check policy enables you to monitor an API instance’s connection to an upstream service
and sends you an email alert if the connection status changes. The Health Check policy monitors the
health of the upstream service and not the health of the API instance or Omni Gateway.

The Health Check policy monitors your API by making GET requests to the specified upstream’s base
path. You must specify a base path with a GET request. Requests are made at a fixed schedule every
minute with the first request. The first request occurs a minute after the policy is applied.
Requests made by the Health Check policy do not count as Omni Gateway API calls for pricing
purposes.

When you configure Health Check, specify a response code for the GET request that indicates a
healthy connection. For example, the status code of an active API should return 200, indicating the
API can receive connections. The platform sends an email alert when the status code is not 200.
Health Check only validates the response code, so what is returned to the endpoint is unimportant.

No logging event appears for healthy responses. Omni Gateway logs only unhealthy responses.

You can use any 1xx, 2xx, 3xx, 4xx, or 5xx response codes. However, if you expect successful
connections to your endpoints, 2xx response codes are ideal. Only a number response code is
accepted.

You are required to create an alert for the Health Check policy. Applying the policy navigates you
to the Create Alert page, where you must create an alert. For information about how to configure
your alert, visit [Using Omni Gateway API Alerts](https://docs.mulesoft.com/gateway/1.13/use-api-alerts).

> [!IMPORTANT] Applying the Health Check policy to API Instances with an outbound TLS context also
> applied causes the Health Check policy to return an unhealthy connection.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Health Check policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Upstream URL</p></div></div></td><td><div><div><p>The full URL of the API upstream you are monitoring</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Base path</p></div></div></td><td><div><div><p>The HTTP path of the GET method that is requested during health checks</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Response code</p></div></div></td><td><div><div><p>The expected status code of the GET request specified in the base path. Only a number response code is accepted.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=a70d8692e52d4c4aaa1b2733ec577108fc932dea6ceb7679c1a789ac4de6ef98 url=/mulesoft/current/en-us/gateway/1.9/policies-included-health-check.md -->

---
product: Omni Gateway
version: 1.9
keywords: health check, api gateway, flex gateway, gateway, policy
---

# Health Check Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Health Check</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Monitors API upstream health at specific intervals</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Health Check policy enables you to monitor an API instance’s connection to an upstream service
and sends you an email alert if the connection status changes. The Health Check policy monitors the
health of the upstream service and not the health of the API instance or Flex Gateway.

The Health Check policy monitors your API by making GET requests to the specified upstream’s base
path. You must specify a base path with a GET request. Requests are made at a fixed schedule every
minute with the first request. The first request occurs a minute after the policy is applied.
Requests made by the Health Check policy do not count as Flex Gateway API calls for pricing
purposes.

When you configure Health Check, specify a response code for the GET request that indicates a
healthy connection. For example, the status code of an active API should return 200, indicating the
API can receive connections. The platform sends an email alert when the status code is not 200.
Health Check only validates the response code, so what is returned to the endpoint is unimportant.

No logging event appears for healthy responses. Flex Gateway logs only unhealthy responses.

You can use any 1xx, 2xx, 3xx, 4xx, or 5xx response codes. However, if you expect successful
connections to your endpoints, 2xx response codes are ideal. Only a number response code is
accepted.

You are required to create an alert for the Health Check policy. Applying the policy navigates you
to the Create Alert page, where you must create an alert. For information about how to configure
your alert, visit [Using Flex Gateway API Alerts](https://docs.mulesoft.com/gateway/1.9/flex-use-api-alerts).

> [!IMPORTANT] Applying the Health Check policy to API Instances with an outbound TLS context also
> applied causes the Health Check policy to return an unhealthy connection.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The Health Check policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Upstream URL</p></div></div></td><td><div><div><p>The full URL of the API upstream you are monitoring</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Base path</p></div></div></td><td><div><div><p>The HTTP path of the GET method that is requested during health checks</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Response code</p></div></div></td><td><div><div><p>The expected status code of the GET request specified in the base path. Only a number response code is accepted.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=bc673f97dd6e6bad09bf619d5f926a5bb21e9a3a4746281fa007792d6b1a0e35 url=/mulesoft/current/en-us/gateway/latest/policies-included-health-check.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: health check, api gateway, flex gateway, gateway, policy
---

# Health Check Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>Health Check</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Monitors API upstream health at specific intervals</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/health-check-release-notes">Health Check Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Health Check policy enables you to monitor an API instance’s connection to an upstream service
and sends you an email alert if the connection status changes. The Health Check policy monitors the
health of the upstream service and not the health of the API instance or Omni Gateway.

The Health Check policy monitors your API by making GET requests to the specified upstream’s base
path. You must specify a base path with a GET request. Requests are made at a fixed schedule every
minute with the first request. The first request occurs a minute after the policy is applied.
Requests made by the Health Check policy do not count as Omni Gateway API calls for pricing
purposes.

When you configure Health Check, specify a response code for the GET request that indicates a
healthy connection. For example, the status code of an active API should return 200, indicating the
API can receive connections. The platform sends an email alert when the status code is not 200.
Health Check only validates the response code, so what is returned to the endpoint is unimportant.

No logging event appears for healthy responses. Omni Gateway logs only unhealthy responses.

You can use any 1xx, 2xx, 3xx, 4xx, or 5xx response codes. However, if you expect successful
connections to your endpoints, 2xx response codes are ideal. Only a number response code is
accepted.

You are required to create an alert for the Health Check policy. Applying the policy navigates you
to the Create Alert page, where you must create an alert. For information about how to configure
your alert, visit [Using Omni Gateway API Alerts](https://docs.mulesoft.com/gateway/latest/use-api-alerts).

> [!IMPORTANT] Applying the Health Check policy to API Instances with an outbound TLS context also
> applied causes the Health Check policy to return an unhealthy connection.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Health Check policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Upstream URL</p></div></div></td><td><div><div><p>The full URL of the API upstream you are monitoring</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Base path</p></div></div></td><td><div><div><p>The HTTP path of the GET method that is requested during health checks</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Response code</p></div></div></td><td><div><div><p>The expected status code of the GET request specified in the base path. Only a number response code is accepted.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=035039ccd21f65696f2cf58a0ef52ee8d15cdb00e65703ae20e1e953d0072fd6 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-dr-ha-overview.md -->

---
product: Omni Gateway
version: 1.12
---

# High Availability and Disaster Recovery

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports high availability (HA) and disaster recovery (DR) through managed deployments
on CloudHub 2.0 and self-managed multi-region deployments. Choose the topic that matches your
deployment type:

- [Managed Flex Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/1.12/flex-architecture-managed-dr-ha)
  — CloudHub 2.0 manages replica deployment, availability zones, and failover for Managed Flex
  Gateway.

- [Self Managed Flex Gateway High Availability, Disaster Recovery, and Multi-Region Deployments](https://docs.mulesoft.com/gateway/1.12/flex-architecture-multi-region)
  — Deploy your self-managed Flex Gateway across multiple regions for latency reduction and live
  failover.

<!-- document id=bdd3ebc70e65e3677048f5bf1608543c7aad51005607a8e112098140fb81c18f url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-dr-ha-overview.md -->

---
product: Omni Gateway
version: 1.13
---

# High Availability and Disaster Recovery

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports high availability (HA) and disaster recovery (DR) through managed deployments
on CloudHub 2.0 and self-managed multi-region deployments. Choose the topic that matches your
deployment type:

- [Managed Omni Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-managed-dr-ha)
  — CloudHub 2.0 manages replica deployment, availability zones, and failover for Managed Omni
  Gateway.

- [Self Managed Omni Gateway High Availability, Disaster Recovery, and Multi-Region Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-multi-region)
  — Deploy your self-managed Omni Gateway across multiple regions for latency reduction and live
  failover.

<!-- document id=4d087c04e05af508833107501e0b079367b372c605f115f494364343a5bd41a6 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-dr-ha-overview.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# High Availability and Disaster Recovery

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports high availability (HA) and disaster recovery (DR) through managed deployments
on CloudHub 2.0 and self-managed multi-region deployments. Choose the topic that matches your
deployment type:

- [Managed Omni Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/latest/gateway-architecture-managed-dr-ha)
  — CloudHub 2.0 manages replica deployment, availability zones, and failover for Managed Omni
  Gateway.

- [Self Managed Omni Gateway High Availability, Disaster Recovery, and Multi-Region Deployments](https://docs.mulesoft.com/gateway/latest/gateway-architecture-multi-region)
  — Deploy your self-managed Omni Gateway across multiple regions for latency reduction and live
  failover.

<!-- document id=45e84af81c7f37bec40ba998a48eec70a859d57a58b724bc6e8dc170a0d560da url=/mulesoft/current/en-us/gateway/1.12/policies-included-http-caching.md -->

---
product: Omni Gateway
version: 1.12
keywords: http caching, api gateway, flex gateway, gateway, policy
---

# HTTP Caching Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>HTTP caching</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Caches HTTP responses from an API implementation</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The HTTP Caching policy enables you to cache HTTP responses for reuse. Caching these responses
speeds up the response time for user requests and reduces the load on the backend. For example, if
your backend exposes an endpoint for which the responses to requests are not likely to change, you
can reuse the HTTP responses and bypass the backend request processing by using the HTTP Caching
policy.

Policies applied after the HTTP Caching policy in the policy order are not applied to responses
served from the cache. For example, a rate limiting policy applied after the HTTP Caching policy
only limits the responses served by the upstream service but not the responses served by the cache.
Apply all policies needed for the cached response before the HTTP Caching policy.

For Self-Managed Gateways, HTTP caching requires that you
[configure shared storage](#configure-shared-storage-for-self-managed-gateway). For Managed
Gateways, Flex Replica shares the cache with each other directly. To learn more about the Managed
Gateway architecture, see
[Managed Flex Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/1.12/flex-architecture-managed-dr-ha).

> [!NOTE] The HTTP Caching policy does not support MCP and A2A server instances.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: http-caching-flex config: httpCachingKey: <string> // REQUIRED, default:
"#\[attributes.requestPath\]" maxCacheEntries: <int> // REQUIRED, default: 10000 ttl: <int> //
REQUIRED, default: 600 useHttpCacheHeaders: <bool> // REQUIRED, default: true invalidationHeader:
<string> // OPTIONAL, default: "" requestExpression: <string> // OPTIONAL, default:
"#\[attributes.method == 'GET' or attributes.method == 'HEAD'\]" responseExpression: <string> //
OPTIONAL, default: "#\[\[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501\] contains
attributes.statusCode\]" distributed: <bool> // REQUIRED, default: false persistCache: <bool> //
REQUIRED, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>httpCachingKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>#[attributes.requestPath]</code></p></div></div></td><td><div><div><p>A DataWeave expression</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Specifies the maximum number of entries that can be stored in the cache at any given time</p></div></div></td></tr><tr><td><div><div><p><code>ttl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache</p></div></div></td></tr><tr><td><div><div><p><code>useHttpCacheHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Enables the use of Cache-Control header directives</p></div></div></td></tr><tr><td><div><div><p><code>invalidationHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div><div><p>A string specifying the header used to invalidate a single entry or the entire cache</p></div></div></td></tr><tr><td><div><div><p><code>requestExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>responseExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>distributed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to be distributed among different nodes in a cluster</p></div></div></td></tr><tr><td><div><div><p><code>persistCache</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to persist between different restarts of the replica</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

#### Resource Configuration Example

```yaml
- policyRef:
    name: http-caching-flex
  config:
    httpCachingKey: "#[attributes.requestPath]"
    maxCacheEntries: 10000
    ttl: 500
    useHttpCacheHeaders: false
    requestExpression: "#[attributes.method == 'GET' or attributes.method == 'HEAD']"
    responseExpression:
      "#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]"
```

#### Configure Shared Storage for Self-Managed Gateway

Self-Managed Gateways require you to configure a shared storage for distributed caching. For more
information about shared storage, refer to
[Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
shared-storage-redis spec: sharedStorage: redis: address: redis:6379 user: user password: pass DB: 1

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-caching
spec: targetRef: kind: ApiInstance name: ingress-http policyRef: kind: Extension name:
http-caching-flex config: httpCachingKey: "#\[attributes.method ++ attributes.requestPath\]"
useHttpCacheHeaders: true maxCacheEntries: 100 ttl: 600 distributed: true persistCache: true
invalidationHeader: AGW-CACHE-CONTROL

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th><th><strong>Required?</strong></th></tr></thead><tbody><tr><td><p>HTTP Caching Key</p></td><td><p>A DataWeave expression. Default value: <code>#[attributes.requestPath]</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Maximum Cache Entries</p></td><td><p>Specifies the maximum number of entries that can be stored in the cache at any given time. Default value: <code>10000</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Entry Time To Live</p></td><td><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache. Default value: <code>600</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Distributed</p></td><td><p>Configures the cache to be distributed among different nodes in a cluster. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Persistent Cache</p></td><td><p>Configures the cache to persist between different restarts of the Flex Gateway instance. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Follow HTTP Caching directives</p></td><td><p>Enables the use of Cache-Control header directives. Default value: <code>true</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Invalidation Header</p></td><td><p>Name of the header used to invalidate a single entry or the entire cache.</p></td><td><p>No</p></td></tr><tr><td><p>Conditional Request Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true). Default value: <code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></td><td><p>No</p></td></tr><tr><td><p>Conditional Response Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true). Default value: <code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></td><td><p>No</p></td></tr></tbody></table>

## How This Policy Works

When an HTTP request reaches an endpoint, what happens next depends on whether that request does not
already exist in cache (a cache miss) or whether it does (a cache hit).

### Cache Miss

1.  The client (user) sends a request to the API.

2.  The request proceeds through other policies in the policy chain before reaching the HTTP Caching
    policy.

3.  The HTTP Caching policy checks if the request is cached. If not, the cache-miss process is
    initiated.

4.  The request continues throughout the chain of other remaining policies.

5.  The request reaches the backend and completes all required processing.

6.  The backend responds and the response travels back through the policy chain.

7.  The response reaches the HTTP Caching policy.

8.  The HTTP Caching policy caches the response for later reuse if it hasn’t already been cached.

9.  The response continues through the remaining policies in the policy chain.

10. The response is returned to the client.

### Cache Hit

1.  The client (user) sends a request to the API.

2.  The request crosses other policies before reaching the HTTP Caching policy.

3.  The HTTP Caching policy verifies that the request is already in the cache.

4.  The [key](#key) is found in the cache and the stored response is returned.

5.  The response continues through the rest of the policy chain until it reaches the last one.

6.  The cached response is returned to the client.

### Stored Entries

_Stored entries_ are the cached HTTP responses. The cache can store any serializable data or input
streams of up to 1 MB. If that value is surpassed, then the reading stops and the value is not
stored in such a case.

### HTTP Caching Key

The cache works as a dictionary, where each response stored in the cache is associated with a string
called _key_. For example, the expression #\[attributes.headers\['key'\]\] uses the header called
`key` as the entry key. You can use any DataWeave expression that returns a string, including
[predefined DataWeave variables](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support#available-predefined-variables).

### Cache Size and Entry Expiration

The cache can hold a specified number of entries at any given time. You can configure this number
using the `Maximum Cache Entries` property. Each stored entry is held in the cache memory for a
specific period of time, after which the entry expires and must be processed again. This expiration
time is called _time to live_ (TTL).

Another condition that can trigger the expiration of an entry is when the cache reaches the maximum
number of items that it can store. When this scenario occurs, the entry is removed by using the FIFO
(First-In First-Out) criteria. This means that the earliest entry to reach the cache is removed,
even though it hasn’t reached the TTL value yet.

### Distributed Cache

Each entry in the cache can be shared between different nodes in a cluster or between several
workers in Runtime Manager using the `Distributed` option (see table). If this option is not
enabled, then each node is assigned its own cache memory.

### Persistent Cache

A persistent cache enables the stored entries in the cache to persist if the Flex Replica is
restarted.

When you upgrade a version of the instance that has the HTTP Caching policy configured to use the
persistent store, the policy tries to maintain the entries stored by the previous version. However
in a worst-case scenario, the entries in the cache are invalidated and the cache is re-populated
when new requests arrive. This manipulation of the entries in the cache occurs automatically and is
invisible to the user.

## HTTP Caching Directives

To obtain more control over the cache, the HTTP Caching policy interprets some of the HTTP
directives from the [RFC-7234](https://tools.ietf.org/html/rfc7234) protocol by taking the following
headers into account:

- `Cache-Control`

- `Expires`

- `Date`

- `Age`

### Cache-Control

The `Cache-Control` header can exist either in the request or in the response. Possible values for
the header, which can be combined separated by commas, include:

- In requests:

  - `no-cache`

The response is not searched for, but is directly stored in the cache.

- `no-store`

The response is not stored in the cache. However, if the response is already present in the cache,
the policy returns the response.

- In responses:

  - `no-store`, `no-cache`, `private`

For each value, the response is not stored in the cache.

- `max-age=<integer>`, `s-maxage=<integer>`

The `<integer>` placeholder must be replaced with a valid integer that indicates the time (in
seconds) for which the response can remain in the cache. If both parameters are defined, `s-maxage`
takes precedence over `max-age`.

If a global time-to-live (TTL) value is also defined for the policy, these header values override
the global TTL configured in the policy if the time specified in the headers is less than the global
TTL.

### Expires

If present, this header specifies the date by which the entry in the cache expires. If you specify
the `max-age` directive or `s-maxage` directive, this header is ignored. You must define the header
value as stated in [RFC-1123](https://tools.ietf.org/html/rfc1123).

### Date

The `date` header, as defined per [RFC-1123](https://tools.ietf.org/html/rfc1123), specifies the
date and time when the response is created. If not defined, the `date` header is added with the time
when the request was received. This header is used in conjunction with the values defined in the
`max-age` and `s-maxage` directives of the Cache-Control header.

### Age

The `age` header indicates the time (in seconds) elapsed since the origin of the cached response
specified in the date header. This header is calculated by the policy and added to each response
that is retrieved from the cache.

The expiration time is calculated using the `cache-control`, `date`, and `expires` headers. However,
if the resulting expiration time exceeds the one imposed by the TTL value of the entry, the cache
entry expires anyway.

### Invalidate

The `invalidate` header, if configured in the HTTP Caching policy, invalidates the entries in the
cache, thereby causing the request to be processed again. You specify the name of the header in the
Invalidation Header configuration to turn on the option. The value of the header can take only one
of the following options: `invalidate`

This option invalidates the entry whose key matches the current request. `invalidate-all` This
option invalidates all the entries from the cache.

For example, imagine that the following values are configured in the policy for the request:

- `HTTP Caching Key`: "#\[attributes.requestPath\]"

- `Invalidation header`: "myInvalidationHeader"

The following command invalidates the entry with key “/my/policy" from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate”`

The following request invalidates all entries from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate-all”`

## Conditional Caching

Conditional caching enables you to configure a set of conditions that must be met before entries are
stored in the cache. If none of the conditional caching parameters are configured, the cache stores
the responses for every incoming request. If configured, parameters are evaluated for each request
to determine whether the response of the current request must be stored.

For conditional request expressions, only the responses for incoming requests with HTTP methods
`GET` or `HEAD` are cached by default. For conditional response expressions, only status codes
specified by [RFC-7231](https://tools.ietf.org/html/rfc7231#section-6.1) are cached by default.

For more information about the default values, see [Configuring Policy Parameters](#cpp).

## FAQ

**What happens when the evaluation of the key results in any error?**

If the evaluation of the expression for a particular request results in an error, the policy does
not take effect and the request continues to the next receptor in the policy chain.

**Can I store only part of the response with this policy?**

No, but you can apply a policy before this one and transform the response to something else.

**What happens if one parameter is configured to search for the response in the cache and the other
parameter is configured for the opposite action?**

This is the same as configuring the response to be stored in the cache when there is a no-store
directive in the Cache-Control header.

In this situation, the response isn’t stored. You must configure both the Cache-Control header and
the cache to be able to store and search for the response in the cache.

**What happens if I do not define some of the optional parameters?**

If you have not configured the `invalidation` header, you cannot invalidate the cache in a request.
Additionally, if you have not configured the request expression or response expression, the cache is
used for all requests and all the responses are stored in the cache (expression #\[true\]).

**Can I modify the Invalidation header values?**

No, you can modify only the header name.

<!-- document id=0389ebce11c978f796e44737a22459020e4f84cb7f42032c1955b5da84d7663e url=/mulesoft/current/en-us/gateway/1.13/policies-included-http-caching.md -->

---
product: Omni Gateway
version: 1.13
keywords: http caching, api gateway, flex gateway, gateway, policy
---

# HTTP Caching Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>HTTP caching</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Caches HTTP responses from an API implementation</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/http-caching-release-notes">HTTP caching</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The HTTP Caching policy enables you to cache HTTP responses for reuse. Caching these responses
speeds up the response time for user requests and reduces the load on the backend. For example, if
your backend exposes an endpoint for which the responses to requests are not likely to change, you
can reuse the HTTP responses and bypass the backend request processing by using the HTTP Caching
policy.

Policies applied after the HTTP Caching policy in the policy order are not applied to responses
served from the cache. For example, a rate limiting policy applied after the HTTP Caching policy
only limits the responses served by the upstream service but not the responses served by the cache.
Apply all policies needed for the cached response before the HTTP Caching policy.

For Self-Managed Gateways, HTTP caching requires that you
[configure shared storage](#configure-shared-storage-for-self-managed-gateway). For Managed
Gateways, Omni Replica shares the cache with each other directly. To learn more about the Managed
Gateway architecture, see
[Managed Omni Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-managed-dr-ha).

> [!NOTE] The HTTP Caching policy does not support MCP and A2A server instances.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: http-caching-flex config: httpCachingKey: <string> // REQUIRED, default:
"#\[attributes.requestPath\]" maxCacheEntries: <int> // REQUIRED, default: 10000 ttl: <int> //
REQUIRED, default: 600 useHttpCacheHeaders: <bool> // REQUIRED, default: true invalidationHeader:
<string> // OPTIONAL, default: "" requestExpression: <string> // OPTIONAL, default:
"#\[attributes.method == 'GET' or attributes.method == 'HEAD'\]" responseExpression: <string> //
OPTIONAL, default: "#\[\[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501\] contains
attributes.statusCode\]" distributed: <bool> // REQUIRED, default: false persistCache: <bool> //
REQUIRED, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>httpCachingKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>#[attributes.requestPath]</code></p></div></div></td><td><div><div><p>A DataWeave expression</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Specifies the maximum number of entries that can be stored in the cache at any given time</p></div></div></td></tr><tr><td><div><div><p><code>ttl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache</p></div></div></td></tr><tr><td><div><div><p><code>useHttpCacheHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Enables the use of Cache-Control header directives</p></div></div></td></tr><tr><td><div><div><p><code>invalidationHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div><div><p>A string specifying the header used to invalidate a single entry or the entire cache</p></div></div></td></tr><tr><td><div><div><p><code>requestExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>responseExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>distributed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to be distributed among different nodes in a cluster</p></div></div></td></tr><tr><td><div><div><p><code>persistCache</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to persist between different restarts of the replica</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

#### Resource Configuration Example

```yaml
- policyRef:
    name: http-caching-flex
  config:
    httpCachingKey: "#[attributes.requestPath]"
    maxCacheEntries: 10000
    ttl: 500
    useHttpCacheHeaders: false
    requestExpression: "#[attributes.method == 'GET' or attributes.method == 'HEAD']"
    responseExpression:
      "#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]"
```

#### Configure Shared Storage for Self-Managed Gateway

Self-Managed Gateways require you to configure shared storage for distributed caching. Configure
either [distributed shared storage](https://docs.mulesoft.com/gateway/1.13/conn-distributed-shared-storage-config) or
[Redis shared storage](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
api-shared-storage spec: sharedStorage: objectStore: url:
distributed://0.0.0.0:30001?join=flex.hostname.com:30001

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-caching
spec: targetRef: kind: ApiInstance name: ingress-http policyRef: kind: Extension name:
http-caching-flex config: httpCachingKey: "#\[attributes.method ++ attributes.requestPath\]"
useHttpCacheHeaders: true maxCacheEntries: 100 ttl: 600 distributed: true persistCache: true
invalidationHeader: AGW-CACHE-CONTROL

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th><th><strong>Required?</strong></th></tr></thead><tbody><tr><td><p>HTTP Caching Key</p></td><td><p>A DataWeave expression. Default value: <code>#[attributes.requestPath]</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Maximum Cache Entries</p></td><td><p>Specifies the maximum number of entries that can be stored in the cache at any given time. Default value: <code>10000</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Entry Time To Live</p></td><td><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache. Default value: <code>600</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Distributed</p></td><td><p>Configures the cache to be distributed among different nodes in a cluster. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Persistent Cache</p></td><td><p>Configures the cache to persist between different restarts of the Omni Gateway instance. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Follow HTTP Caching directives</p></td><td><p>Enables the use of Cache-Control header directives. Default value: <code>true</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Invalidation Header</p></td><td><p>Name of the header used to invalidate a single entry or the entire cache.</p></td><td><p>No</p></td></tr><tr><td><p>Conditional Request Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true). Default value: <code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></td><td><p>No</p></td></tr><tr><td><p>Conditional Response Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true). Default value: <code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></td><td><p>No</p></td></tr></tbody></table>

## How This Policy Works

When an HTTP request reaches an endpoint, what happens next depends on whether that request does not
already exist in cache (a cache miss) or whether it does (a cache hit).

### Cache Miss

1.  The client (user) sends a request to the API.

2.  The request proceeds through other policies in the policy chain before reaching the HTTP Caching
    policy.

3.  The HTTP Caching policy checks if the request is cached. If not, the cache-miss process is
    initiated.

4.  The request continues throughout the chain of other remaining policies.

5.  The request reaches the backend and completes all required processing.

6.  The backend responds and the response travels back through the policy chain.

7.  The response reaches the HTTP Caching policy.

8.  The HTTP Caching policy caches the response for later reuse if it hasn’t already been cached.

9.  The response continues through the remaining policies in the policy chain.

10. The response is returned to the client.

### Cache Hit

1.  The client (user) sends a request to the API.

2.  The request crosses other policies before reaching the HTTP Caching policy.

3.  The HTTP Caching policy verifies that the request is already in the cache.

4.  The [key](#key) is found in the cache and the stored response is returned.

5.  The response continues through the rest of the policy chain until it reaches the last one.

6.  The cached response is returned to the client.

### Stored Entries

_Stored entries_ are the cached HTTP responses. The cache can store any serializable data or input
streams of up to 1 MB. If that value is surpassed, then the reading stops and the value is not
stored in such a case.

### HTTP Caching Key

The cache works as a dictionary, where each response stored in the cache is associated with a string
called _key_. For example, the expression #\[attributes.headers\['key'\]\] uses the header called
`key` as the entry key. You can use any DataWeave expression that returns a string, including
[predefined DataWeave variables](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support#available-predefined-variables).

### Cache Size and Entry Expiration

The cache can hold a specified number of entries at any given time. You can configure this number
using the `Maximum Cache Entries` property. Each stored entry is held in the cache memory for a
specific period of time, after which the entry expires and must be processed again. This expiration
time is called _time to live_ (TTL).

Another condition that can trigger the expiration of an entry is when the cache reaches the maximum
number of items that it can store. When this scenario occurs, the entry is removed by using the FIFO
(First-In First-Out) criteria. This means that the earliest entry to reach the cache is removed,
even though it hasn’t reached the TTL value yet.

### Distributed Cache

Each entry in the cache can be shared between different nodes in a cluster or between several
workers in Runtime Manager using the `Distributed` option (see table). If this option is not
enabled, then each node is assigned its own cache memory.

### Persistent Cache

A persistent cache enables the stored entries in the cache to persist if the Omni Replica is
restarted.

When you upgrade a version of the instance that has the HTTP Caching policy configured to use the
persistent store, the policy tries to maintain the entries stored by the previous version. However
in a worst-case scenario, the entries in the cache are invalidated and the cache is re-populated
when new requests arrive. This manipulation of the entries in the cache occurs automatically and is
invisible to the user.

## HTTP Caching Directives

To obtain more control over the cache, the HTTP Caching policy interprets some of the HTTP
directives from the [RFC-7234](https://tools.ietf.org/html/rfc7234) protocol by taking the following
headers into account:

- `Cache-Control`

- `Expires`

- `Date`

- `Age`

### Cache-Control

The `Cache-Control` header can exist either in the request or in the response. Possible values for
the header, which can be combined separated by commas, include:

- In requests:

  - `no-cache`

The response is not searched for, but is directly stored in the cache.

- `no-store`

The response is not stored in the cache. However, if the response is already present in the cache,
the policy returns the response.

- In responses:

  - `no-store`, `no-cache`, `private`

For each value, the response is not stored in the cache.

- `max-age=<integer>`, `s-maxage=<integer>`

The `<integer>` placeholder must be replaced with a valid integer that indicates the time (in
seconds) for which the response can remain in the cache. If both parameters are defined, `s-maxage`
takes precedence over `max-age`.

If a global time-to-live (TTL) value is also defined for the policy, these header values override
the global TTL configured in the policy if the time specified in the headers is less than the global
TTL.

### Expires

If present, this header specifies the date by which the entry in the cache expires. If you specify
the `max-age` directive or `s-maxage` directive, this header is ignored. You must define the header
value as stated in [RFC-1123](https://tools.ietf.org/html/rfc1123).

### Date

The `date` header, as defined per [RFC-1123](https://tools.ietf.org/html/rfc1123), specifies the
date and time when the response is created. If not defined, the `date` header is added with the time
when the request was received. This header is used in conjunction with the values defined in the
`max-age` and `s-maxage` directives of the Cache-Control header.

### Age

The `age` header indicates the time (in seconds) elapsed since the origin of the cached response
specified in the date header. This header is calculated by the policy and added to each response
that is retrieved from the cache.

The expiration time is calculated using the `cache-control`, `date`, and `expires` headers. However,
if the resulting expiration time exceeds the one imposed by the TTL value of the entry, the cache
entry expires anyway.

### Invalidate

The `invalidate` header, if configured in the HTTP Caching policy, invalidates the entries in the
cache, thereby causing the request to be processed again. You specify the name of the header in the
Invalidation Header configuration to turn on the option. The value of the header can take only one
of the following options: `invalidate`

This option invalidates the entry whose key matches the current request. `invalidate-all` This
option invalidates all the entries from the cache.

For example, imagine that the following values are configured in the policy for the request:

- `HTTP Caching Key`: "#\[attributes.requestPath\]"

- `Invalidation header`: "myInvalidationHeader"

The following command invalidates the entry with key “/my/policy" from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate”`

The following request invalidates all entries from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate-all”`

## Conditional Caching

Conditional caching enables you to configure a set of conditions that must be met before entries are
stored in the cache. If none of the conditional caching parameters are configured, the cache stores
the responses for every incoming request. If configured, parameters are evaluated for each request
to determine whether the response of the current request must be stored.

For conditional request expressions, only the responses for incoming requests with HTTP methods
`GET` or `HEAD` are cached by default. For conditional response expressions, only status codes
specified by [RFC-7231](https://tools.ietf.org/html/rfc7231#section-6.1) are cached by default.

For more information about the default values, see [Configuring Policy Parameters](#cpp).

## FAQ

**What happens when the evaluation of the key results in any error?**

If the evaluation of the expression for a particular request results in an error, the policy does
not take effect and the request continues to the next receptor in the policy chain.

**Can I store only part of the response with this policy?**

No, but you can apply a policy before this one and transform the response to something else.

**What happens if one parameter is configured to search for the response in the cache and the other
parameter is configured for the opposite action?**

This is the same as configuring the response to be stored in the cache when there is a no-store
directive in the Cache-Control header.

In this situation, the response isn’t stored. You must configure both the Cache-Control header and
the cache to be able to store and search for the response in the cache.

**What happens if I do not define some of the optional parameters?**

If you have not configured the `invalidation` header, you cannot invalidate the cache in a request.
Additionally, if you have not configured the request expression or response expression, the cache is
used for all requests and all the responses are stored in the cache (expression #\[true\]).

**Can I modify the Invalidation header values?**

No, you can modify only the header name.

<!-- document id=ef0b73193c55fa62c6b8843ff604ff01eef6319504251e03adeb1cc4e042ac7b url=/mulesoft/current/en-us/gateway/1.9/policies-included-http-caching.md -->

---
product: Omni Gateway
version: 1.9
keywords: http caching, api gateway, flex gateway, gateway, policy
---

# HTTP Caching Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>HTTP caching</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Caches HTTP responses from an API implementation</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The HTTP Caching policy enables you to cache HTTP responses for reuse. Caching these responses
speeds up the response time for user requests and reduces the load on the backend. For example, if
your backend exposes an endpoint for which the responses to requests are not likely to change, you
can reuse the HTTP responses and bypass the backend request processing by using the HTTP Caching
policy.

Policies applied after the HTTP Caching policy in the policy order are not applied to responses
served from the cache. For example, a rate limiting policy applied after the HTTP Caching policy
only limits the responses served by the upstream service but not the responses served by the cache.
Apply all policies needed for the cached response before the HTTP Caching policy.

> [!NOTE] The HTTP Caching policy does not support MCP and A2A server instances.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: http-caching-flex config: httpCachingKey: <string> // REQUIRED, default:
"#\[attributes.requestPath\]" maxCacheEntries: <int> // REQUIRED, default: 10000 ttl: <int> //
REQUIRED, default: 600 useHttpCacheHeaders: <bool> // REQUIRED, default: true invalidationHeader:
<string> // OPTIONAL, default: "" requestExpression: <string> // OPTIONAL, default:
"#\[attributes.method == 'GET' or attributes.method == 'HEAD'\]" responseExpression: <string> //
OPTIONAL, default: "#\[\[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501\] contains
attributes.statusCode\]" distributed: <bool> // REQUIRED, default: false persistCache: <bool> //
REQUIRED, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>httpCachingKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>#[attributes.requestPath]</code></p></div></div></td><td><div><div><p>A DataWeave expression</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Specifies the maximum number of entries that can be stored in the cache at any given time</p></div></div></td></tr><tr><td><div><div><p><code>ttl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache</p></div></div></td></tr><tr><td><div><div><p><code>useHttpCacheHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Enables the use of Cache-Control header directives</p></div></div></td></tr><tr><td><div><div><p><code>invalidationHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div><div><p>A string specifying the header used to invalidate a single entry or the entire cache</p></div></div></td></tr><tr><td><div><div><p><code>requestExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>responseExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>distributed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to be distributed among different nodes in a cluster</p></div></div></td></tr><tr><td><div><div><p><code>persistCache</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to persist between different restarts of the replica</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

#### Resource Configuration Example

```yaml
- policyRef:
    name: http-caching-flex
  config:
    httpCachingKey: "#[attributes.requestPath]"
    maxCacheEntries: 10000
    ttl: 500
    useHttpCacheHeaders: false
    requestExpression: "#[attributes.method == 'GET' or attributes.method == 'HEAD']"
    responseExpression:
      "#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]"
```

#### Distributed Caching Resource Configuration Example

Distributed Caching requires Shared Storage to be enabled. For more information about Shared
Storage, refer to
[Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
shared-storage-redis spec: sharedStorage: redis: address: redis:6379 user: user password: pass DB: 1

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-caching
spec: targetRef: kind: ApiInstance name: ingress-http policyRef: kind: Extension name:
http-caching-flex config: httpCachingKey: "#\[attributes.method ++ attributes.requestPath\]"
useHttpCacheHeaders: true maxCacheEntries: 100 ttl: 600 distributed: true persistCache: true
invalidationHeader: AGW-CACHE-CONTROL

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th><th><strong>Required?</strong></th></tr></thead><tbody><tr><td><p>HTTP Caching Key</p></td><td><p>A DataWeave expression. Default value: <code>#[attributes.requestPath]</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Maximum Cache Entries</p></td><td><p>Specifies the maximum number of entries that can be stored in the cache at any given time. Default value: <code>10000</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Entry Time To Live</p></td><td><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache. Default value: <code>600</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Distributed</p></td><td><p>Configures the cache to be distributed among different nodes in a cluster. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Persistent Cache</p></td><td><p>Configures the cache to persist between different restarts of the Flex Gateway instance. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Follow HTTP Caching directives</p></td><td><p>Enables the use of Cache-Control header directives. Default value: <code>true</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Invalidation Header</p></td><td><p>Name of the header used to invalidate a single entry or the entire cache.</p></td><td><p>No</p></td></tr><tr><td><p>Conditional Request Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true). Default value: <code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></td><td><p>No</p></td></tr><tr><td><p>Conditional Response Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true). Default value: <code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></td><td><p>No</p></td></tr></tbody></table>

## How This Policy Works

When an HTTP request reaches an endpoint, what happens next depends on whether that request does not
already exist in cache (a cache miss) or whether it does (a cache hit).

### Cache Miss

In a cache miss scenario, the HTTP Caching policy checks whether a response to the submitted request
is already cached. The request reaches the backend and the process is initiated only when it’s a
cache miss. The diagram illustrates the flow of events that occur in this scenario:

![A flowchart that illustrates the data flow between a web browser and a backend system](/mulesoft/current/en-us/gateway/1.9/_images/http-policy-cache-miss.png)

1.  The client (user) sends a request to the API.

2.  The request proceeds through other policies in the policy chain before reaching the HTTP Caching
    policy.

3.  The HTTP Caching policy checks if the request is already in the object store and, if not, the
    cache miss process is initiated.

4.  The request continues throughout the chain of other remaining policies.

5.  The request reaches the backend and completes all required processing.

6.  The backend responds and the response travels back through the policy chain.

7.  The response reaches the HTTP Caching policy.

8.  Caching hits the object store again and attempts to save the [key](#key) of the request for
    later reuse.

9.  The response continues through the remaining policies in the policy chain.

10. The response is returned to the client.

### Cache Hit

In a cache hit scenario, the HTTP Caching policy searches for the key in the object store and finds
that the response to a request is already cached as a [stored entry](#stored_entry). The request
does not proceed any further in the policy chain toward the backend, and the cached response is
reused.

Subsequently, all the policies that must be executed in the policy chain after caching are not
executed, in case of a cache hit:

![A flowchart diagram illustrating the data flow from a web browser through an API gateway to the backend and the object store](/mulesoft/current/en-us/gateway/1.9/_images/http-policy-cache-hit.png)

1.  The client (user) sends a request to the API.

2.  The request crosses other policies before reaching the HTTP Caching policy.

3.  The HTTP Caching policy verifies that the request is already in the cache.

4.  The [key](#key) is found in the object store and the stored response is returned.

5.  The response continues through the rest of the policy chain until it reaches the last one.

6.  The cached response is returned to the client.

### Stored Entries

_Stored entries_ are the cached HTTP responses. The cache can store any serializable data or input
streams of up to 1 MB. If that value is surpassed, then the reading stops and the value is not
stored in such a case.

### HTTP Caching Key

The cache works as a dictionary, where each response stored in the cache is associated with a string
called _key_. For example, the expression #\[attributes.headers\['key'\]\] uses the header called
`key` as the entry key. You can use any DataWeave expression that returns a string, including
[predefined DataWeave variables](https://docs.mulesoft.com/gateway/1.9/policies-flex-dataweave-support#available-predefined-variables).

### Cache Size and Entry Expiration

The cache can hold a specified number of entries at any given time. You can configure this number
using the `Maximum Cache Entries` property. Each stored entry is held in the cache memory for a
specific period of time, after which the entry expires and must be processed again. This expiration
time is called _time to live_ (TTL).

Another condition that can trigger the expiration of an entry is when the cache reaches the maximum
number of items that it can store. When this scenario occurs, the entry is removed by using the FIFO
(First-In First-Out) criteria. This means that the earliest entry to reach the cache is removed,
even though it hasn’t reached the TTL value yet.

### Distributed Cache

Each entry in the cache can be shared between different nodes in a cluster or between several
workers in Runtime Manager using the `Distributed` option (see table). If this option is not
enabled, then each node is assigned its own cache memory.

### Persistent Cache

A persistent cache enables the stored entries in the cache to persist if the Flex Replica is
restarted.

When you upgrade a version of the instance that has the HTTP Caching policy configured to use the
persistent store, the policy tries to maintain the entries stored by the previous version. However
in a worst-case scenario, the entries in the cache are invalidated and the cache is re-populated
when new requests arrive. This manipulation of the entries in the cache occurs automatically and is
invisible to the user.

## HTTP Caching Directives

To obtain more control over the cache, the HTTP Caching policy interprets some of the HTTP
directives from the [RFC-7234](https://datatracker.ietf.org/doc/html/rfc7234) protocol by taking the
following headers into account:

- `Cache-Control`

- `Expires`

- `Date`

- `Age`

### Cache-Control

The `Cache-Control` header can exist either in the request or in the response. Possible values for
the header, which can be combined separated by commas, include:

- In requests:

  - `no-cache`

The response is not searched for, but is directly stored in the cache.

- `no-store`

The response is not stored in the cache. However, if the response is already present in the cache,
the policy returns the response.

- In responses:

  - `no-store`, `no-cache`, `private`

For each value, the response is not stored in the cache.

- `max-age=<integer>`, `s-maxage=<integer>`

The `<integer>` placeholder must be replaced with a valid integer that indicates the time (in
seconds) for which the response can remain in the cache. If both parameters are defined, `s-maxage`
takes precedence over `max-age`.

If a global time-to-live (TTL) value is also defined for the policy, these header values override
the global TTL configured in the policy if the time specified in the headers is less than the global
TTL.

### Expires

If present, this header specifies the date by which the entry in the cache expires. If you specify
the `max-age` directive or `s-maxage` directive, this header is ignored. You must define the header
value as stated in [RFC-1123](https://datatracker.ietf.org/doc/html/rfc1123).

### Date

The `date` header, as defined per [RFC-1123](https://datatracker.ietf.org/doc/html/rfc1123),
specifies the date and time when the response is created. If not defined, the `date` header is added
with the time when the request was received. This header is used in conjunction with the values
defined in the `max-age` and `s-maxage` directives of the Cache-Control header.

### Age

The `age` header indicates the time (in seconds) elapsed since the origin of the cached response
specified in the date header. This header is calculated by the policy and added to each response
that is retrieved from the cache.

The expiration time is calculated using the `cache-control`, `date`, and `expires` headers. However,
if the resulting expiration time exceeds the one imposed by the TTL value of the entry, the cache
entry expires anyway.

### Invalidate

The `invalidate` header, if configured in the HTTP Caching policy, invalidates the entries in the
cache, thereby causing the request to be processed again. You specify the name of the header in the
Invalidation Header configuration to turn on the option. The value of the header can take only one
of the following options: `invalidate`

This option invalidates the entry whose key matches the current request. `invalidate-all` This
option invalidates all the entries from the cache.

For example, imagine that the following values are configured in the policy for the request:

- `HTTP Caching Key`: "#\[attributes.requestPath\]"

- `Invalidation header`: "myInvalidationHeader"

The following command invalidates the entry with key “/my/policy" from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate”`

The following request invalidates all entries from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate-all”`

## Conditional Caching

Conditional caching enables you to configure a set of conditions that must be met before entries are
stored in the cache. If none of the conditional caching parameters are configured, the cache stores
the responses for every incoming request. If configured, parameters are evaluated for each request
to determine whether the response of the current request must be stored.

For conditional request expressions, only the responses for incoming requests with HTTP methods
`GET` or `HEAD` are cached by default. For conditional response expressions, only status codes
specified by [RFC-7231](https://datatracker.ietf.org/doc/html/rfc7231) are cached by default.

For more information about the default values, see [Configuring Policy Parameters](#cpp).

## FAQ

**What happens when the evaluation of the key results in any error?**

If the evaluation of the expression for a particular request results in an error, the policy does
not take effect and the request continues to the next receptor in the policy chain.

**Can I store only part of the response with this policy?**

No, but you can apply a policy before this one and transform the response to something else.

**What happens if one parameter is configured to search for the response in the cache and the other
parameter is configured for the opposite action?**

This is the same as configuring the response to be stored in the cache when there is a no-store
directive in the Cache-Control header.

In this situation, the response isn’t stored. You must configure both the Cache-Control header and
the cache to be able to store and search for the response in the cache.

**What happens if I do not define some of the optional parameters?**

If you have not configured the `invalidation` header, you cannot invalidate the cache in a request.
Additionally, if you have not configured the request expression or response expression, the cache is
used for all requests and all the responses are stored in the cache (expression #\[true\]).

**Can I modify the Invalidation header values?**

No, you can modify only the header name.

<!-- document id=5d09372f50bde027252f958ec12a7b7cf9f4c6eb33237a4bd9416e00ecf5169e url=/mulesoft/current/en-us/gateway/latest/policies-included-http-caching.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: http caching, api gateway, flex gateway, gateway, policy
---

# HTTP Caching Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>HTTP caching</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Caches HTTP responses from an API implementation</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/http-caching-release-notes">HTTP caching</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The HTTP Caching policy enables you to cache HTTP responses for reuse. Caching these responses
speeds up the response time for user requests and reduces the load on the backend. For example, if
your backend exposes an endpoint for which the responses to requests are not likely to change, you
can reuse the HTTP responses and bypass the backend request processing by using the HTTP Caching
policy.

Policies applied after the HTTP Caching policy in the policy order are not applied to responses
served from the cache. For example, a rate limiting policy applied after the HTTP Caching policy
only limits the responses served by the upstream service but not the responses served by the cache.
Apply all policies needed for the cached response before the HTTP Caching policy.

For Self-Managed Gateways, HTTP caching works out of the box using the default local (filesystem)
storage, which persists the cache across restarts. To share the cache across replicas,
[configure distributed or Redis shared storage](#configure-shared-storage-for-self-managed-gateway).
For Managed Gateways, Omni Replica shares the cache with each other directly. To learn more about
the Managed Gateway architecture, see
[Managed Omni Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/latest/gateway-architecture-managed-dr-ha).

> [!NOTE] The HTTP Caching policy does not support MCP and A2A server instances.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: http-caching-flex config: httpCachingKey: <string> // REQUIRED, default:
"#\[attributes.requestPath\]" maxCacheEntries: <int> // REQUIRED, default: 10000 ttl: <int> //
REQUIRED, default: 600 useHttpCacheHeaders: <bool> // REQUIRED, default: true invalidationHeader:
<string> // OPTIONAL, default: "" requestExpression: <string> // OPTIONAL, default:
"#\[attributes.method == 'GET' or attributes.method == 'HEAD'\]" responseExpression: <string> //
OPTIONAL, default: "#\[\[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501\] contains
attributes.statusCode\]" distributed: <bool> // REQUIRED, default: false persistCache: <bool> //
REQUIRED, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>httpCachingKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>#[attributes.requestPath]</code></p></div></div></td><td><div><div><p>A DataWeave expression</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Specifies the maximum number of entries that can be stored in the cache at any given time</p></div></div></td></tr><tr><td><div><div><p><code>ttl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache</p></div></div></td></tr><tr><td><div><div><p><code>useHttpCacheHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Enables the use of Cache-Control header directives</p></div></div></td></tr><tr><td><div><div><p><code>invalidationHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div><div><p>A string specifying the header used to invalidate a single entry or the entire cache</p></div></div></td></tr><tr><td><div><div><p><code>requestExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>responseExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>distributed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to be distributed among different nodes in a cluster</p></div></div></td></tr><tr><td><div><div><p><code>persistCache</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to persist between different restarts of the replica</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

#### Resource Configuration Example

```yaml
- policyRef:
    name: http-caching-flex
  config:
    httpCachingKey: "#[attributes.requestPath]"
    maxCacheEntries: 10000
    ttl: 500
    useHttpCacheHeaders: false
    requestExpression: "#[attributes.method == 'GET' or attributes.method == 'HEAD']"
    responseExpression:
      "#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]"
```

#### Configure Shared Storage for Self-Managed Gateway

Distributed caching across replicas requires distributed or Redis shared storage, because the
default local (filesystem) storage is not shared between replicas. Configure either
[distributed shared storage](https://docs.mulesoft.com/gateway/latest/conn-distributed-shared-storage-config) or
[Redis shared storage](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
api-shared-storage spec: sharedStorage: objectStore: url:
distributed://0.0.0.0:30001?join=flex.hostname.com:30001

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-caching
spec: targetRef: kind: ApiInstance name: ingress-http policyRef: kind: Extension name:
http-caching-flex config: httpCachingKey: "#\[attributes.method ++ attributes.requestPath\]"
useHttpCacheHeaders: true maxCacheEntries: 100 ttl: 600 distributed: true persistCache: true
invalidationHeader: AGW-CACHE-CONTROL

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th><th><strong>Required?</strong></th></tr></thead><tbody><tr><td><p>HTTP Caching Key</p></td><td><p>A DataWeave expression. Default value: <code>#[attributes.requestPath]</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Maximum Cache Entries</p></td><td><p>Specifies the maximum number of entries that can be stored in the cache at any given time. Default value: <code>10000</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Entry Time To Live</p></td><td><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache. Default value: <code>600</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Distributed</p></td><td><p>Configures the cache to be distributed among different nodes in a cluster. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Persistent Cache</p></td><td><p>Configures the cache to persist between different restarts of the Omni Gateway instance. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Follow HTTP Caching directives</p></td><td><p>Enables the use of Cache-Control header directives. Default value: <code>true</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Invalidation Header</p></td><td><p>Name of the header used to invalidate a single entry or the entire cache.</p></td><td><p>No</p></td></tr><tr><td><p>Conditional Request Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true). Default value: <code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></td><td><p>No</p></td></tr><tr><td><p>Conditional Response Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true). Default value: <code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></td><td><p>No</p></td></tr></tbody></table>

## How This Policy Works

When an HTTP request reaches an endpoint, what happens next depends on whether that request does not
already exist in cache (a cache miss) or whether it does (a cache hit).

### Cache Miss

1.  The client (user) sends a request to the API.

2.  The request proceeds through other policies in the policy chain before reaching the HTTP Caching
    policy.

3.  The HTTP Caching policy checks if the request is cached. If not, the cache-miss process is
    initiated.

4.  The request continues throughout the chain of other remaining policies.

5.  The request reaches the backend and completes all required processing.

6.  The backend responds and the response travels back through the policy chain.

7.  The response reaches the HTTP Caching policy.

8.  The HTTP Caching policy caches the response for later reuse if it hasn’t already been cached.

9.  The response continues through the remaining policies in the policy chain.

10. The response is returned to the client.

### Cache Hit

1.  The client (user) sends a request to the API.

2.  The request crosses other policies before reaching the HTTP Caching policy.

3.  The HTTP Caching policy verifies that the request is already in the cache.

4.  The [key](#key) is found in the cache and the stored response is returned.

5.  The response continues through the rest of the policy chain until it reaches the last one.

6.  The cached response is returned to the client.

### Stored Entries

_Stored entries_ are the cached HTTP responses. The cache can store any serializable data or input
streams of up to 1 MB. If that value is surpassed, then the reading stops and the value is not
stored in such a case.

### HTTP Caching Key

The cache works as a dictionary, where each response stored in the cache is associated with a string
called _key_. For example, the expression #\[attributes.headers\['key'\]\] uses the header called
`key` as the entry key. You can use any DataWeave expression that returns a string, including
[predefined DataWeave variables](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support#available-predefined-variables).

### Cache Size and Entry Expiration

The cache can hold a specified number of entries at any given time. You can configure this number
using the `Maximum Cache Entries` property. Each stored entry is held in the cache memory for a
specific period of time, after which the entry expires and must be processed again. This expiration
time is called _time to live_ (TTL).

Another condition that can trigger the expiration of an entry is when the cache reaches the maximum
number of items that it can store. When this scenario occurs, the entry is removed by using the FIFO
(First-In First-Out) criteria. This means that the earliest entry to reach the cache is removed,
even though it hasn’t reached the TTL value yet.

### Distributed Cache

Each entry in the cache can be shared between different nodes in a cluster or between several
workers in Runtime Manager using the `Distributed` option (see table). If this option is not
enabled, then each node is assigned its own cache memory.

### Persistent Cache

A persistent cache enables the stored entries in the cache to persist if the Omni Replica is
restarted.

When you upgrade a version of the instance that has the HTTP Caching policy configured to use the
persistent store, the policy tries to maintain the entries stored by the previous version. However
in a worst-case scenario, the entries in the cache are invalidated and the cache is re-populated
when new requests arrive. This manipulation of the entries in the cache occurs automatically and is
invisible to the user.

## HTTP Caching Directives

To obtain more control over the cache, the HTTP Caching policy interprets some of the HTTP
directives from the [RFC-7234](https://tools.ietf.org/html/rfc7234) protocol by taking the following
headers into account:

- `Cache-Control`

- `Expires`

- `Date`

- `Age`

### Cache-Control

The `Cache-Control` header can exist either in the request or in the response. Possible values for
the header, which can be combined separated by commas, include:

- In requests:

  - `no-cache`

The response is not searched for, but is directly stored in the cache.

- `no-store`

The response is not stored in the cache. However, if the response is already present in the cache,
the policy returns the response.

- In responses:

  - `no-store`, `no-cache`, `private`

For each value, the response is not stored in the cache.

- `max-age=<integer>`, `s-maxage=<integer>`

The `<integer>` placeholder must be replaced with a valid integer that indicates the time (in
seconds) for which the response can remain in the cache. If both parameters are defined, `s-maxage`
takes precedence over `max-age`.

If a global time-to-live (TTL) value is also defined for the policy, these header values override
the global TTL configured in the policy if the time specified in the headers is less than the global
TTL.

### Expires

If present, this header specifies the date by which the entry in the cache expires. If you specify
the `max-age` directive or `s-maxage` directive, this header is ignored. You must define the header
value as stated in [RFC-1123](https://tools.ietf.org/html/rfc1123).

### Date

The `date` header, as defined per [RFC-1123](https://tools.ietf.org/html/rfc1123), specifies the
date and time when the response is created. If not defined, the `date` header is added with the time
when the request was received. This header is used in conjunction with the values defined in the
`max-age` and `s-maxage` directives of the Cache-Control header.

### Age

The `age` header indicates the time (in seconds) elapsed since the origin of the cached response
specified in the date header. This header is calculated by the policy and added to each response
that is retrieved from the cache.

The expiration time is calculated using the `cache-control`, `date`, and `expires` headers. However,
if the resulting expiration time exceeds the one imposed by the TTL value of the entry, the cache
entry expires anyway.

### Invalidate

The `invalidate` header, if configured in the HTTP Caching policy, invalidates the entries in the
cache, thereby causing the request to be processed again. You specify the name of the header in the
Invalidation Header configuration to turn on the option. The value of the header can take only one
of the following options: `invalidate`

This option invalidates the entry whose key matches the current request. `invalidate-all` This
option invalidates all the entries from the cache.

For example, imagine that the following values are configured in the policy for the request:

- `HTTP Caching Key`: "#\[attributes.requestPath\]"

- `Invalidation header`: "myInvalidationHeader"

The following command invalidates the entry with key “/my/policy" from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate”`

The following request invalidates all entries from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate-all”`

## Conditional Caching

Conditional caching enables you to configure a set of conditions that must be met before entries are
stored in the cache. If none of the conditional caching parameters are configured, the cache stores
the responses for every incoming request. If configured, parameters are evaluated for each request
to determine whether the response of the current request must be stored.

For conditional request expressions, only the responses for incoming requests with HTTP methods
`GET` or `HEAD` are cached by default. For conditional response expressions, only status codes
specified by [RFC-7231](https://tools.ietf.org/html/rfc7231#section-6.1) are cached by default.

For more information about the default values, see [Configuring Policy Parameters](#cpp).

## FAQ

**What happens when the evaluation of the key results in any error?**

If the evaluation of the expression for a particular request results in an error, the policy does
not take effect and the request continues to the next receptor in the policy chain.

**Can I store only part of the response with this policy?**

No, but you can apply a policy before this one and transform the response to something else.

**What happens if one parameter is configured to search for the response in the cache and the other
parameter is configured for the opposite action?**

This is the same as configuring the response to be stored in the cache when there is a no-store
directive in the Cache-Control header.

In this situation, the response isn’t stored. You must configure both the Cache-Control header and
the cache to be able to store and search for the response in the cache.

**What happens if I do not define some of the optional parameters?**

If you have not configured the `invalidation` header, you cannot invalidate the cache in a request.
Additionally, if you have not configured the request expression or response expression, the cache is
used for all requests and all the responses are stored in the cache (expression #\[true\]).

**Can I modify the Invalidation header values?**

No, you can modify only the header name.

<!-- document id=0a9172e315b3bc83f6dd55bb2ebd66c6fbf71bb9a91923cbf87bd72fa5cd8a8c url=/mulesoft/current/en-us/gateway/1.12/policies-custom-flex-implement-rust.md -->

---
product: Omni Gateway
version: 1.12
---

# Implement a Flex Gateway Custom Policy in Rust

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

## Summary

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. You implement these policies using the
[WebAssembly for Proxies (Rust SDK)](https://github.com/proxy-wasm/proxy-wasm-rust-sdk). The
following examples assume knowledge about Rust and related tools.

## Lifecycle Events

Custom policies are based on [proxy-wasm ABI](https://github.com/proxy-wasm/spec), an event-driven,
Envoy-agnostic, low-level interface for L4/L7 proxies. This interface specifies how a WASM extension
and its host interact, and it includes listenable lifecycle events: HTTP request lifecycle events
and also WASM filter lifecycle events.

The SDK exposes a method to retrieve information related to each lifecycle event. For example, data
retrieved from the `on_http_request_headers` event can be used to perform related custom policy
logic, which can then inform the runtime if the request should be processed.

### HTTP Request Lifecycle Events

- `on_http_request_headers`

  Triggered when the endpoint receives the complete set of HTTP request headers.

- `on_http_request_body`

  Triggered when the endpoint receives the first bytes of the HTTP request.

- `on_http_response_headers`

  Triggered when the endpoint receives the complete set of HTTP response headers.

- `on_http_response_body`

  Triggered when the endpoint receives the first bytes of the HTTP response body.

### Filter Lifecycle Events

- `on_configure`

  Triggered when the WASM filter starts with an available configuration.

  Flex Gateway serializes policy configuration into JSON, which is used to configure the Envoy WASM
  filter. You can deserialize and parse this JSON into data that will be used by your custom policy.

### Example Lifecycle Events Implementation

The following Envoy filter template demonstrates how to implement lifecycle events:

use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*;

proxy\_wasm::main! {{
    proxy\_wasm::set\_log\_level(LogLevel::Trace);
    proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
        Box::new(HttpConfigHeaderRoot {
            header\_content: String::new(),
        })
    });
}}

struct HttpConfigHeader { header\_content: String, }

impl Context for HttpConfigHeader {}

impl HttpContext for HttpConfigHeader { fn on\_http\_request\_headers(&mut self, \_num\_headers:
usize, \_end\_of\_stream: bool) -> Action { Action::Continue }

    fn on\_http\_request\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_headers(&mut self, \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

}

struct HttpConfigHeaderRoot { header\_content: String, }

impl Context for HttpConfigHeaderRoot {}

impl RootContext for HttpConfigHeaderRoot { fn on\_configure(&mut self, \_: usize) -> bool { if let
Some(config\_bytes) = self.get\_plugin\_configuration() { self.header\_content =
String::from\_utf8(config\_bytes).unwrap() } true }

    fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
        Some(Box::new(HttpConfigHeader {
            header\_content: self.header\_content.clone(),
        }))
    }

    fn get\_type(&self) -> Option<ContextType> {
        Some(ContextType::HttpContext)
    }

}

## Custom Authentication Header Policy Example

The following tutorial describes how to create an example policy implementation for a
[Policy Definition](https://docs.mulesoft.com/gateway/1.12/policies-custom-flex-getting-started#create-policy-definition-files) that has
already been published in Exchange. The example policy blocks requests whose `x-custom-auth` header
does not match a user-configured value.

During the policy development process, you complete the following steps:

1.  Create the policy definition JSON file.

2.  Set up the project.

3.  Develop the custom policy.

### Create the Policy Definition JSON File

Example policy implementations require a policy definition JSON file. Flex Gateway passes policy
configuration as JSON with that policy definition structure to the Envoy WASM filter.

The example authentication header policy has only one parameter: the value that needs to be passed
in the header. The policy definition JSON file should match the following:

{ "title": "Custom Auth Header", "type": "object", "description": "Enforces HTTP authentication
matching x-custom-auth value to what is configured in the policy.", "properties": { "secret-value":
{ "title": "Custom Auth Header Password", "type": "string", "@context": { "@characteristics": \[
"security:sensitive" \] } } }, "required": \[ "secret-value" \], "unevaluatedProperties": false,
"@context": { "@vocab": "anypoint://vocabulary/policy.yaml#", "security":
"anypoint://vocabulary/policy.yaml#" }, "$id": "custom-auth-header-simple",
  "$schema":
"https://json-schema.org/draft/2019-09/schema" }

### Set Up the Project

1.  Create the Rust project via the following command:

    cargo new flex\_custom\_policy\_example --lib

    This creates a `flex_custom_policy_example` directory.

2.  Copy the following into `Cargo.toml`, located in the `flex_custom_policy_example` directory:

    \[package\] name = "flex\_custom\_policy\_example" version = "0.1.0" edition = "2021"

    # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

    \[lib\] crate-type = \["cdylib"\] name="flex\_custom\_policy\_example" path="src/lib.rs"

    \[dependencies\] proxy-wasm = { git = "https://github.com/proxy-wasm/proxy-wasm-rust-sdk.git",
    tag = "v0.2.0" } serde = { version = "1.0", features = \["derive"\] } serde\_json = "1.0"

    \[profile.release\] opt-level = "z" lto = "fat"

### Develop the Custom Policy

1.  Add the following policy bootstrapping code to a new Rust source file:

    use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*; use serde::Deserialize;

    proxy\_wasm::main! {{
        proxy\_wasm::set\_log\_level(LogLevel::Trace);
        proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
            Box::new(CustomAuthRootContext {
                config: CustomAuthConfig::default(),
            })
        });
    }}

    The code is required to deploy your WASM filter to Envoy. The `main` block sets the root
    context, which is an Envoy entity used to generate the child context for each incoming HTTP
    request.

2.  Add the following root context implementation code:

    struct CustomAuthRootContext { config: CustomAuthConfig, }

    impl Context for CustomAuthRootContext {}

    impl RootContext for CustomAuthRootContext {

        fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
            Some(Box::new(CustomAuthHttpContext {
                config: self.config.clone(),
            }))
        }

        fn get\_type(&self) -> Option<ContextType> {
            Some(ContextType::HttpContext)
        }

    }

    Each Envoy filter is required to provide a root context implementation. The `RootContext` trait
    contains useful methods you can implement. In this example, HTTP filters implement
    `create_http_context` and `get_type` so that Envoy can generate the child contexts.

3.  Add the following `Struct` to enable parsing this JSON:

    #\[derive(Default, Clone, Deserialize)\] struct CustomAuthConfig {

        #\[serde(alias = "secret-value")\]
        secret\_value: String,

    }

    Flex Gateway configures your policy with JSON defined in the policy definition. The JSON that
    needs to be parsed contains a single field called `secret-value`.

4.  Deserialize the configuration:

    After creating the basic policy configuration structure, you must implement the `RootContext`
    `on_configure` method in order to deserialize it.

    Within the implementation of `RootContext` for `CustomAuthRootContext`, add the `on_configure`
    method, like the following snippet.

    impl RootContext for CustomAuthRootContext {

        fn on\_configure(&mut self, \_: usize) -> bool {
            if let Some(config\_bytes) = self.get\_plugin\_configuration() {
                self.config = serde\_json::from\_slice(config\_bytes.as\_slice()).unwrap();
            }

            true
        }

        // Other implemented methods
        // ...

    }

5.  Add the following HTTP context code:

    struct CustomAuthHttpContext { pub config: CustomAuthConfig, }

    impl Context for CustomAuthHttpContext {}

    impl HttpContext for CustomAuthHttpContext {}

    Each incoming request creates a new `CustomAuthHttpContext`, and this `CustomAuthHttpContext`
    lives as long as the HTTP request lives. This enables you to store request-related state data
    (but not inter-request state data.)

6.  Add the following core policy functionality logic:

    impl HttpContext for CustomAuthHttpContext { fn on\_http\_request\_headers(&mut self,
    \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {

            if let Some(value) = self.get\_http\_request\_header("x-custom-auth") {
                if self.config.secret\_value == value {
                    return Action::Continue;
                }
            }

            self.send\_http\_response(401, Vec::new(), None);

            Action::Pause
        }

    }

    The `proxy-wasm` ABI retrieves the header value of the incoming request and then compares the
    value against `secret-value`. If `secret-value` matches the header, the implementation returns
    an `Action::Continue`. Otherwise, it returns `Action::Pause`, and the filter itself emits a
    response to the calling client using `send_http_response`.

    Note: The Rust SDK contains an issue reading non-UTF-8 values with `get_http_request_header`. To
    work around the issue, use the `get_http_request_headers_bytes` method and read the bytes using
    the `from_utf8`
    [method](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8). For example:

    let header =
    self.get\_http\_request\_header\_bytes("x-custom-auth").map(String::from\_utf8).and\_then(Result::ok);

7.  Enable compilation by adding `wasm32` as a target:

    rustup target add wasm32-wasi

    All third-party libraries included in your policy must be compatible with the `wasm32-wasi` Rust
    compilation target.

    > [!IMPORTANT] Some libraries might compile properly to the wasm32-wasi target but might not
    > work properly when deployed to Flex Gateway. Example deployment errors when this happens are:
    >
    > - `Failed to load Wasm module due to a missing import`
    >
    > - `Wasm VM failed to initialize Wasm code`
    >
    > - `Plugin configured to fail closed failed to load`
    >
    > To resolve these issues, contact the owners of the third-party library or use a different
    > library.

8.  Compile your custom policy via the following command:

    cargo build --target wasm32-wasi --release

    Compilation outputs a binary `.wasm` file into the `./target/wasm32-wasi/release` directory.

    For more information on pushing custom policies to Exchange, refer to
    [Publish a Flex Gateway or Mule 4 Custom Policy](https://docs.mulesoft.com/gateway/1.12/policies-custom-flex-getting-started).

<!-- document id=e8c988e34935d8a33e832b92287a27d8881a42388d9096447db7525ff0ff647f url=/mulesoft/current/en-us/gateway/1.9/policies-custom-flex-implement-rust.md -->

---
product: Omni Gateway
version: 1.9
---

# Implement a Flex Gateway Custom Policy in Rust

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

## Summary

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. You implement these policies using the
[WebAssembly for Proxies (Rust SDK)](https://github.com/proxy-wasm/proxy-wasm-rust-sdk). The
following examples assume knowledge about Rust and related tools.

## Lifecycle Events

Custom policies are based on [proxy-wasm ABI](https://github.com/proxy-wasm/spec), an event-driven,
Envoy-agnostic, low-level interface for L4/L7 proxies. This interface specifies how a WASM extension
and its host interact, and it includes listenable lifecycle events: HTTP request lifecycle events
and also WASM filter lifecycle events.

The SDK exposes a method to retrieve information related to each lifecycle event. For example, data
retrieved from the `on_http_request_headers` event can be used to perform related custom policy
logic, which can then inform the runtime if the request should be processed.

### HTTP Request Lifecycle Events

- `on_http_request_headers`

  Triggered when the endpoint receives the complete set of HTTP request headers.

- `on_http_request_body`

  Triggered when the endpoint receives the first bytes of the HTTP request.

- `on_http_response_headers`

  Triggered when the endpoint receives the complete set of HTTP response headers.

- `on_http_response_body`

  Triggered when the endpoint receives the first bytes of the HTTP response body.

### Filter Lifecycle Events

- `on_configure`

  Triggered when the WASM filter starts with an available configuration.

  Flex Gateway serializes policy configuration into JSON, which is used to configure the Envoy WASM
  filter. You can deserialize and parse this JSON into data that will be used by your custom policy.

### Example Lifecycle Events Implementation

The following Envoy filter template demonstrates how to implement lifecycle events:

use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*;

proxy\_wasm::main! {{
    proxy\_wasm::set\_log\_level(LogLevel::Trace);
    proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
        Box::new(HttpConfigHeaderRoot {
            header\_content: String::new(),
        })
    });
}}

struct HttpConfigHeader { header\_content: String, }

impl Context for HttpConfigHeader {}

impl HttpContext for HttpConfigHeader { fn on\_http\_request\_headers(&mut self, \_num\_headers:
usize, \_end\_of\_stream: bool) -> Action { Action::Continue }

    fn on\_http\_request\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_headers(&mut self, \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

}

struct HttpConfigHeaderRoot { header\_content: String, }

impl Context for HttpConfigHeaderRoot {}

impl RootContext for HttpConfigHeaderRoot { fn on\_configure(&mut self, \_: usize) -> bool { if let
Some(config\_bytes) = self.get\_plugin\_configuration() { self.header\_content =
String::from\_utf8(config\_bytes).unwrap() } true }

    fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
        Some(Box::new(HttpConfigHeader {
            header\_content: self.header\_content.clone(),
        }))
    }

    fn get\_type(&self) -> Option<ContextType> {
        Some(ContextType::HttpContext)
    }

}

## Custom Authentication Header Policy Example

The following tutorial describes how to create an example policy implementation for a
[Policy Definition](https://docs.mulesoft.com/gateway/1.9/policies-custom-flex-getting-started#create-policy-definition-files) that has
already been published in Exchange. The example policy blocks requests whose `x-custom-auth` header
does not match a user-configured value.

During the policy development process, you complete the following steps:

1.  Create the policy definition JSON file.

2.  Set up the project.

3.  Develop the custom policy.

### Create the Policy Definition JSON File

Example policy implementations require a policy definition JSON file. Flex Gateway passes policy
configuration as JSON with that policy definition structure to the Envoy WASM filter.

The example authentication header policy has only one parameter: the value that needs to be passed
in the header. The policy definition JSON file should match the following:

{ "title": "Custom Auth Header", "type": "object", "description": "Enforces HTTP authentication
matching x-custom-auth value to what is configured in the policy.", "properties": { "secret-value":
{ "title": "Custom Auth Header Password", "type": "string", "@context": { "@characteristics": \[
"security:sensitive" \] } } }, "required": \[ "secret-value" \], "unevaluatedProperties": false,
"@context": { "@vocab": "anypoint://vocabulary/policy.yaml#", "security":
"anypoint://vocabulary/policy.yaml#" }, "$id": "custom-auth-header-simple",
  "$schema":
"https://json-schema.org/draft/2019-09/schema" }

### Set Up the Project

1.  Create the Rust project via the following command:

    cargo new flex\_custom\_policy\_example --lib

    This creates a `flex_custom_policy_example` directory.

2.  Copy the following into `Cargo.toml`, located in the `flex_custom_policy_example` directory:

    \[package\] name = "flex\_custom\_policy\_example" version = "0.1.0" edition = "2021"

    # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

    \[lib\] crate-type = \["cdylib"\] name="flex\_custom\_policy\_example" path="src/lib.rs"

    \[dependencies\] proxy-wasm = { git = "https://github.com/proxy-wasm/proxy-wasm-rust-sdk.git",
    tag = "v0.2.0" } serde = { version = "1.0", features = \["derive"\] } serde\_json = "1.0"

    \[profile.release\] opt-level = "z" lto = "fat"

### Develop the Custom Policy

1.  Add the following policy bootstrapping code to a new Rust source file:

    use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*; use serde::Deserialize;

    proxy\_wasm::main! {{
        proxy\_wasm::set\_log\_level(LogLevel::Trace);
        proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
            Box::new(CustomAuthRootContext {
                config: CustomAuthConfig::default(),
            })
        });
    }}

    The code is required to deploy your WASM filter to Envoy. The `main` block sets the root
    context, which is an Envoy entity used to generate the child context for each incoming HTTP
    request.

2.  Add the following root context implementation code:

    struct CustomAuthRootContext { config: CustomAuthConfig, }

    impl Context for CustomAuthRootContext {}

    impl RootContext for CustomAuthRootContext {

        fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
            Some(Box::new(CustomAuthHttpContext {
                config: self.config.clone(),
            }))
        }

        fn get\_type(&self) -> Option<ContextType> {
            Some(ContextType::HttpContext)
        }

    }

    Each Envoy filter is required to provide a root context implementation. The `RootContext` trait
    contains useful methods you can implement. In this example, HTTP filters implement
    `create_http_context` and `get_type` so that Envoy can generate the child contexts.

3.  Add the following `Struct` to enable parsing this JSON:

    #\[derive(Default, Clone, Deserialize)\] struct CustomAuthConfig {

        #\[serde(alias = "secret-value")\]
        secret\_value: String,

    }

    Flex Gateway configures your policy with JSON defined in the policy definition. The JSON that
    needs to be parsed contains a single field called `secret-value`.

4.  Deserialize the configuration:

    After creating the basic policy configuration structure, you must implement the `RootContext`
    `on_configure` method in order to deserialize it.

    Within the implementation of `RootContext` for `CustomAuthRootContext`, add the `on_configure`
    method, like the following snippet.

    impl RootContext for CustomAuthRootContext {

        fn on\_configure(&mut self, \_: usize) -> bool {
            if let Some(config\_bytes) = self.get\_plugin\_configuration() {
                self.config = serde\_json::from\_slice(config\_bytes.as\_slice()).unwrap();
            }

            true
        }

        // Other implemented methods
        // ...

    }

5.  Add the following HTTP context code:

    struct CustomAuthHttpContext { pub config: CustomAuthConfig, }

    impl Context for CustomAuthHttpContext {}

    impl HttpContext for CustomAuthHttpContext {}

    Each incoming request creates a new `CustomAuthHttpContext`, and this `CustomAuthHttpContext`
    lives as long as the HTTP request lives. This enables you to store request-related state data
    (but not inter-request state data.)

6.  Add the following core policy functionality logic:

    impl HttpContext for CustomAuthHttpContext { fn on\_http\_request\_headers(&mut self,
    \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {

            if let Some(value) = self.get\_http\_request\_header("x-custom-auth") {
                if self.config.secret\_value == value {
                    return Action::Continue;
                }
            }

            self.send\_http\_response(401, Vec::new(), None);

            Action::Pause
        }

    }

    The `proxy-wasm` ABI retrieves the header value of the incoming request and then compares the
    value against `secret-value`. If `secret-value` matches the header, the implementation returns
    an `Action::Continue`. Otherwise, it returns `Action::Pause`, and the filter itself emits a
    response to the calling client using `send_http_response`.

    Note: The Rust SDK contains an issue reading non-UTF-8 values with `get_http_request_header`. To
    work around the issue, use the `get_http_request_headers_bytes` method and read the bytes using
    the `from_utf8`
    [method](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8). For example:

    let header =
    self.get\_http\_request\_header\_bytes("x-custom-auth").map(String::from\_utf8).and\_then(Result::ok);

7.  Enable compilation by adding `wasm32` as a target:

    rustup target add wasm32-wasi

    All third-party libraries included in your policy must be compatible with the `wasm32-wasi` Rust
    compilation target.

    > [!IMPORTANT] Some libraries might compile properly to the wasm32-wasi target but might not
    > work properly when deployed to Flex Gateway. Example deployment errors when this happens are:
    >
    > - `Failed to load Wasm module due to a missing import`
    >
    > - `Wasm VM failed to initialize Wasm code`
    >
    > - `Plugin configured to fail closed failed to load`
    >
    > To resolve these issues, contact the owners of the third-party library or use a different
    > library.

8.  Compile your custom policy via the following command:

    cargo build --target wasm32-wasi --release

    Compilation outputs a binary `.wasm` file into the `./target/wasm32-wasi/release` directory.

    For more information on pushing custom policies to Exchange, refer to
    [Publish a Flex Gateway or Mule 4 Custom Policy](https://docs.mulesoft.com/gateway/1.9/policies-custom-flex-getting-started).

<!-- document id=f89d121e09cce3ecd7b9425aaa9a21b3c20824e2c27f80f332b9af63609e1e56 url=/mulesoft/current/en-us/gateway/1.13/policies-custom-implement-rust.md -->

---
product: Omni Gateway
version: 1.13
---

# Implement an Omni Gateway Custom Policy in Rust

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

## Summary

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. You implement these policies using the
[WebAssembly for Proxies (Rust SDK)](https://github.com/proxy-wasm/proxy-wasm-rust-sdk). The
following examples assume knowledge about Rust and related tools.

## Lifecycle Events

Custom policies are based on [proxy-wasm ABI](https://github.com/proxy-wasm/spec), an event-driven,
Envoy-agnostic, low-level interface for L4/L7 proxies. This interface specifies how a WASM extension
and its host interact, and it includes listenable lifecycle events: HTTP request lifecycle events
and also WASM filter lifecycle events.

The SDK exposes a method to retrieve information related to each lifecycle event. For example, data
retrieved from the `on_http_request_headers` event can be used to perform related custom policy
logic, which can then inform the runtime if the request should be processed.

### HTTP Request Lifecycle Events

- `on_http_request_headers`

  Triggered when the endpoint receives the complete set of HTTP request headers.

- `on_http_request_body`

  Triggered when the endpoint receives the first bytes of the HTTP request.

- `on_http_response_headers`

  Triggered when the endpoint receives the complete set of HTTP response headers.

- `on_http_response_body`

  Triggered when the endpoint receives the first bytes of the HTTP response body.

### Filter Lifecycle Events

- `on_configure`

  Triggered when the WASM filter starts with an available configuration.

  Omni Gateway serializes policy configuration into JSON, which is used to configure the Envoy WASM
  filter. You can deserialize and parse this JSON into data that will be used by your custom policy.

### Example Lifecycle Events Implementation

The following Envoy filter template demonstrates how to implement lifecycle events:

use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*;

proxy\_wasm::main! {{
    proxy\_wasm::set\_log\_level(LogLevel::Trace);
    proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
        Box::new(HttpConfigHeaderRoot {
            header\_content: String::new(),
        })
    });
}}

struct HttpConfigHeader { header\_content: String, }

impl Context for HttpConfigHeader {}

impl HttpContext for HttpConfigHeader { fn on\_http\_request\_headers(&mut self, \_num\_headers:
usize, \_end\_of\_stream: bool) -> Action { Action::Continue }

    fn on\_http\_request\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_headers(&mut self, \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

}

struct HttpConfigHeaderRoot { header\_content: String, }

impl Context for HttpConfigHeaderRoot {}

impl RootContext for HttpConfigHeaderRoot { fn on\_configure(&mut self, \_: usize) -> bool { if let
Some(config\_bytes) = self.get\_plugin\_configuration() { self.header\_content =
String::from\_utf8(config\_bytes).unwrap() } true }

    fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
        Some(Box::new(HttpConfigHeader {
            header\_content: self.header\_content.clone(),
        }))
    }

    fn get\_type(&self) -> Option<ContextType> {
        Some(ContextType::HttpContext)
    }

}

## Custom Authentication Header Policy Example

The following tutorial describes how to create an example policy implementation for a
[Policy Definition](https://docs.mulesoft.com/gateway/1.13/policies-custom-getting-started#create-policy-definition-files) that has already
been published in Exchange. The example policy blocks requests whose `x-custom-auth` header does not
match a user-configured value.

During the policy development process, you complete the following steps:

1.  Create the policy definition JSON file.

2.  Set up the project.

3.  Develop the custom policy.

### Create the Policy Definition JSON File

Example policy implementations require a policy definition JSON file. Omni Gateway passes policy
configuration as JSON with that policy definition structure to the Envoy WASM filter.

The example authentication header policy has only one parameter: the value that needs to be passed
in the header. The policy definition JSON file should match the following:

{ "title": "Custom Auth Header", "type": "object", "description": "Enforces HTTP authentication
matching x-custom-auth value to what is configured in the policy.", "properties": { "secret-value":
{ "title": "Custom Auth Header Password", "type": "string", "@context": { "@characteristics": \[
"security:sensitive" \] } } }, "required": \[ "secret-value" \], "unevaluatedProperties": false,
"@context": { "@vocab": "anypoint://vocabulary/policy.yaml#", "security":
"anypoint://vocabulary/policy.yaml#" }, "$id": "custom-auth-header-simple",
  "$schema":
"https://json-schema.org/draft/2019-09/schema" }

### Set Up the Project

1.  Create the Rust project via the following command:

    cargo new flex\_custom\_policy\_example --lib

    This creates a `flex_custom_policy_example` directory.

2.  Copy the following into `Cargo.toml`, located in the `flex_custom_policy_example` directory:

    \[package\] name = "flex\_custom\_policy\_example" version = "0.1.0" edition = "2021"

    # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

    \[lib\] crate-type = \["cdylib"\] name="flex\_custom\_policy\_example" path="src/lib.rs"

    \[dependencies\] proxy-wasm = { git = "https://github.com/proxy-wasm/proxy-wasm-rust-sdk.git",
    tag = "v0.2.0" } serde = { version = "1.0", features = \["derive"\] } serde\_json = "1.0"

    \[profile.release\] opt-level = "z" lto = "fat"

### Develop the Custom Policy

1.  Add the following policy bootstrapping code to a new Rust source file:

    use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*; use serde::Deserialize;

    proxy\_wasm::main! {{
        proxy\_wasm::set\_log\_level(LogLevel::Trace);
        proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
            Box::new(CustomAuthRootContext {
                config: CustomAuthConfig::default(),
            })
        });
    }}

    The code is required to deploy your WASM filter to Envoy. The `main` block sets the root
    context, which is an Envoy entity used to generate the child context for each incoming HTTP
    request.

2.  Add the following root context implementation code:

    struct CustomAuthRootContext { config: CustomAuthConfig, }

    impl Context for CustomAuthRootContext {}

    impl RootContext for CustomAuthRootContext {

        fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
            Some(Box::new(CustomAuthHttpContext {
                config: self.config.clone(),
            }))
        }

        fn get\_type(&self) -> Option<ContextType> {
            Some(ContextType::HttpContext)
        }

    }

    Each Envoy filter is required to provide a root context implementation. The `RootContext` trait
    contains useful methods you can implement. In this example, HTTP filters implement
    `create_http_context` and `get_type` so that Envoy can generate the child contexts.

3.  Add the following `Struct` to enable parsing this JSON:

    #\[derive(Default, Clone, Deserialize)\] struct CustomAuthConfig {

        #\[serde(alias = "secret-value")\]
        secret\_value: String,

    }

    Omni Gateway configures your policy with JSON defined in the policy definition. The JSON that
    needs to be parsed contains a single field called `secret-value`.

4.  Deserialize the configuration:

    After creating the basic policy configuration structure, you must implement the `RootContext`
    `on_configure` method in order to deserialize it.

    Within the implementation of `RootContext` for `CustomAuthRootContext`, add the `on_configure`
    method, like the following snippet.

    impl RootContext for CustomAuthRootContext {

        fn on\_configure(&mut self, \_: usize) -> bool {
            if let Some(config\_bytes) = self.get\_plugin\_configuration() {
                self.config = serde\_json::from\_slice(config\_bytes.as\_slice()).unwrap();
            }

            true
        }

        // Other implemented methods
        // ...

    }

5.  Add the following HTTP context code:

    struct CustomAuthHttpContext { pub config: CustomAuthConfig, }

    impl Context for CustomAuthHttpContext {}

    impl HttpContext for CustomAuthHttpContext {}

    Each incoming request creates a new `CustomAuthHttpContext`, and this `CustomAuthHttpContext`
    lives as long as the HTTP request lives. This enables you to store request-related state data
    (but not inter-request state data.)

6.  Add the following core policy functionality logic:

    impl HttpContext for CustomAuthHttpContext { fn on\_http\_request\_headers(&mut self,
    \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {

            if let Some(value) = self.get\_http\_request\_header("x-custom-auth") {
                if self.config.secret\_value == value {
                    return Action::Continue;
                }
            }

            self.send\_http\_response(401, Vec::new(), None);

            Action::Pause
        }

    }

    The `proxy-wasm` ABI retrieves the header value of the incoming request and then compares the
    value against `secret-value`. If `secret-value` matches the header, the implementation returns
    an `Action::Continue`. Otherwise, it returns `Action::Pause`, and the filter itself emits a
    response to the calling client using `send_http_response`.

    Note: The Rust SDK contains an issue reading non-UTF-8 values with `get_http_request_header`. To
    work around the issue, use the `get_http_request_headers_bytes` method and read the bytes using
    the `from_utf8`
    [method](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8). For example:

    let header =
    self.get\_http\_request\_header\_bytes("x-custom-auth").map(String::from\_utf8).and\_then(Result::ok);

7.  Enable compilation by adding `wasm32` as a target:

    rustup target add wasm32-wasi

    All third-party libraries included in your policy must be compatible with the `wasm32-wasi` Rust
    compilation target.

    > [!IMPORTANT] Some libraries might compile properly to the wasm32-wasi target but might not
    > work properly when deployed to Omni Gateway. Example deployment errors when this happens are:
    >
    > - `Failed to load Wasm module due to a missing import`
    >
    > - `Wasm VM failed to initialize Wasm code`
    >
    > - `Plugin configured to fail closed failed to load`
    >
    > To resolve these issues, contact the owners of the third-party library or use a different
    > library.

8.  Compile your custom policy via the following command:

    cargo build --target wasm32-wasi --release

    Compilation outputs a binary `.wasm` file into the `./target/wasm32-wasi/release` directory.

    For more information on pushing custom policies to Exchange, refer to
    [Publish an Omni Gateway or Mule 4 Custom Policy](https://docs.mulesoft.com/gateway/1.13/policies-custom-getting-started).

<!-- document id=74f43e3c1f54cc0b58b0f813ee50e38b793e7401a22c9e191e5cb7d832ebd2d0 url=/mulesoft/current/en-us/gateway/latest/policies-custom-implement-rust.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Implement an Omni Gateway Custom Policy in Rust

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

## Summary

You can implement custom policies via WebAssembly (WASM) extensions that run on Envoy as custom
filters. You implement these policies using the
[WebAssembly for Proxies (Rust SDK)](https://github.com/proxy-wasm/proxy-wasm-rust-sdk). The
following examples assume knowledge about Rust and related tools.

## Lifecycle Events

Custom policies are based on [proxy-wasm ABI](https://github.com/proxy-wasm/spec), an event-driven,
Envoy-agnostic, low-level interface for L4/L7 proxies. This interface specifies how a WASM extension
and its host interact, and it includes listenable lifecycle events: HTTP request lifecycle events
and also WASM filter lifecycle events.

The SDK exposes a method to retrieve information related to each lifecycle event. For example, data
retrieved from the `on_http_request_headers` event can be used to perform related custom policy
logic, which can then inform the runtime if the request should be processed.

### HTTP Request Lifecycle Events

- `on_http_request_headers`

  Triggered when the endpoint receives the complete set of HTTP request headers.

- `on_http_request_body`

  Triggered when the endpoint receives the first bytes of the HTTP request.

- `on_http_response_headers`

  Triggered when the endpoint receives the complete set of HTTP response headers.

- `on_http_response_body`

  Triggered when the endpoint receives the first bytes of the HTTP response body.

### Filter Lifecycle Events

- `on_configure`

  Triggered when the WASM filter starts with an available configuration.

  Omni Gateway serializes policy configuration into JSON, which is used to configure the Envoy WASM
  filter. You can deserialize and parse this JSON into data that will be used by your custom policy.

### Example Lifecycle Events Implementation

The following Envoy filter template demonstrates how to implement lifecycle events:

use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*;

proxy\_wasm::main! {{
    proxy\_wasm::set\_log\_level(LogLevel::Trace);
    proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
        Box::new(HttpConfigHeaderRoot {
            header\_content: String::new(),
        })
    });
}}

struct HttpConfigHeader { header\_content: String, }

impl Context for HttpConfigHeader {}

impl HttpContext for HttpConfigHeader { fn on\_http\_request\_headers(&mut self, \_num\_headers:
usize, \_end\_of\_stream: bool) -> Action { Action::Continue }

    fn on\_http\_request\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_headers(&mut self, \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

    fn on\_http\_response\_body(&mut self, \_body\_size: usize, \_end\_of\_stream: bool) -> Action {
        Action::Continue
    }

}

struct HttpConfigHeaderRoot { header\_content: String, }

impl Context for HttpConfigHeaderRoot {}

impl RootContext for HttpConfigHeaderRoot { fn on\_configure(&mut self, \_: usize) -> bool { if let
Some(config\_bytes) = self.get\_plugin\_configuration() { self.header\_content =
String::from\_utf8(config\_bytes).unwrap() } true }

    fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
        Some(Box::new(HttpConfigHeader {
            header\_content: self.header\_content.clone(),
        }))
    }

    fn get\_type(&self) -> Option<ContextType> {
        Some(ContextType::HttpContext)
    }

}

## Custom Authentication Header Policy Example

The following tutorial describes how to create an example policy implementation for a
[Policy Definition](https://docs.mulesoft.com/gateway/latest/policies-custom-getting-started#create-policy-definition-files) that has already
been published in Exchange. The example policy blocks requests whose `x-custom-auth` header does not
match a user-configured value.

During the policy development process, you complete the following steps:

1.  Create the policy definition JSON file.

2.  Set up the project.

3.  Develop the custom policy.

### Create the Policy Definition JSON File

Example policy implementations require a policy definition JSON file. Omni Gateway passes policy
configuration as JSON with that policy definition structure to the Envoy WASM filter.

The example authentication header policy has only one parameter: the value that needs to be passed
in the header. The policy definition JSON file should match the following:

{ "title": "Custom Auth Header", "type": "object", "description": "Enforces HTTP authentication
matching x-custom-auth value to what is configured in the policy.", "properties": { "secret-value":
{ "title": "Custom Auth Header Password", "type": "string", "@context": { "@characteristics": \[
"security:sensitive" \] } } }, "required": \[ "secret-value" \], "unevaluatedProperties": false,
"@context": { "@vocab": "anypoint://vocabulary/policy.yaml#", "security":
"anypoint://vocabulary/policy.yaml#" }, "$id": "custom-auth-header-simple",
  "$schema":
"https://json-schema.org/draft/2019-09/schema" }

### Set Up the Project

1.  Create the Rust project via the following command:

    cargo new flex\_custom\_policy\_example --lib

    This creates a `flex_custom_policy_example` directory.

2.  Copy the following into `Cargo.toml`, located in the `flex_custom_policy_example` directory:

    \[package\] name = "flex\_custom\_policy\_example" version = "0.1.0" edition = "2021"

    # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

    \[lib\] crate-type = \["cdylib"\] name="flex\_custom\_policy\_example" path="src/lib.rs"

    \[dependencies\] proxy-wasm = { git = "https://github.com/proxy-wasm/proxy-wasm-rust-sdk.git",
    tag = "v0.2.0" } serde = { version = "1.0", features = \["derive"\] } serde\_json = "1.0"

    \[profile.release\] opt-level = "z" lto = "fat"

### Develop the Custom Policy

1.  Add the following policy bootstrapping code to a new Rust source file:

    use proxy\_wasm::traits::\*; use proxy\_wasm::types::\*; use serde::Deserialize;

    proxy\_wasm::main! {{
        proxy\_wasm::set\_log\_level(LogLevel::Trace);
        proxy\_wasm::set\_root\_context(|\_| -> Box<dyn RootContext> {
            Box::new(CustomAuthRootContext {
                config: CustomAuthConfig::default(),
            })
        });
    }}

    The code is required to deploy your WASM filter to Envoy. The `main` block sets the root
    context, which is an Envoy entity used to generate the child context for each incoming HTTP
    request.

2.  Add the following root context implementation code:

    struct CustomAuthRootContext { config: CustomAuthConfig, }

    impl Context for CustomAuthRootContext {}

    impl RootContext for CustomAuthRootContext {

        fn create\_http\_context(&self, \_: u32) -> Option<Box<dyn HttpContext>> {
            Some(Box::new(CustomAuthHttpContext {
                config: self.config.clone(),
            }))
        }

        fn get\_type(&self) -> Option<ContextType> {
            Some(ContextType::HttpContext)
        }

    }

    Each Envoy filter is required to provide a root context implementation. The `RootContext` trait
    contains useful methods you can implement. In this example, HTTP filters implement
    `create_http_context` and `get_type` so that Envoy can generate the child contexts.

3.  Add the following `Struct` to enable parsing this JSON:

    #\[derive(Default, Clone, Deserialize)\] struct CustomAuthConfig {

        #\[serde(alias = "secret-value")\]
        secret\_value: String,

    }

    Omni Gateway configures your policy with JSON defined in the policy definition. The JSON that
    needs to be parsed contains a single field called `secret-value`.

4.  Deserialize the configuration:

    After creating the basic policy configuration structure, you must implement the `RootContext`
    `on_configure` method in order to deserialize it.

    Within the implementation of `RootContext` for `CustomAuthRootContext`, add the `on_configure`
    method, like the following snippet.

    impl RootContext for CustomAuthRootContext {

        fn on\_configure(&mut self, \_: usize) -> bool {
            if let Some(config\_bytes) = self.get\_plugin\_configuration() {
                self.config = serde\_json::from\_slice(config\_bytes.as\_slice()).unwrap();
            }

            true
        }

        // Other implemented methods
        // ...

    }

5.  Add the following HTTP context code:

    struct CustomAuthHttpContext { pub config: CustomAuthConfig, }

    impl Context for CustomAuthHttpContext {}

    impl HttpContext for CustomAuthHttpContext {}

    Each incoming request creates a new `CustomAuthHttpContext`, and this `CustomAuthHttpContext`
    lives as long as the HTTP request lives. This enables you to store request-related state data
    (but not inter-request state data.)

6.  Add the following core policy functionality logic:

    impl HttpContext for CustomAuthHttpContext { fn on\_http\_request\_headers(&mut self,
    \_num\_headers: usize, \_end\_of\_stream: bool) -> Action {

            if let Some(value) = self.get\_http\_request\_header("x-custom-auth") {
                if self.config.secret\_value == value {
                    return Action::Continue;
                }
            }

            self.send\_http\_response(401, Vec::new(), None);

            Action::Pause
        }

    }

    The `proxy-wasm` ABI retrieves the header value of the incoming request and then compares the
    value against `secret-value`. If `secret-value` matches the header, the implementation returns
    an `Action::Continue`. Otherwise, it returns `Action::Pause`, and the filter itself emits a
    response to the calling client using `send_http_response`.

    Note: The Rust SDK contains an issue reading non-UTF-8 values with `get_http_request_header`. To
    work around the issue, use the `get_http_request_headers_bytes` method and read the bytes using
    the `from_utf8`
    [method](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8). For example:

    let header =
    self.get\_http\_request\_header\_bytes("x-custom-auth").map(String::from\_utf8).and\_then(Result::ok);

7.  Enable compilation by adding `wasm32` as a target:

    rustup target add wasm32-wasi

    All third-party libraries included in your policy must be compatible with the `wasm32-wasi` Rust
    compilation target.

    > [!IMPORTANT] Some libraries might compile properly to the wasm32-wasi target but might not
    > work properly when deployed to Omni Gateway. Example deployment errors when this happens are:
    >
    > - `Failed to load Wasm module due to a missing import`
    >
    > - `Wasm VM failed to initialize Wasm code`
    >
    > - `Plugin configured to fail closed failed to load`
    >
    > To resolve these issues, contact the owners of the third-party library or use a different
    > library.

8.  Compile your custom policy via the following command:

    cargo build --target wasm32-wasi --release

    Compilation outputs a binary `.wasm` file into the `./target/wasm32-wasi/release` directory.

    For more information on pushing custom policies to Exchange, refer to
    [Publish an Omni Gateway or Mule 4 Custom Policy](https://docs.mulesoft.com/gateway/latest/policies-custom-getting-started).

<!-- document id=c4ea5014bb59b1cebb3a4f440849471d058d3dcc9d13e725df9eca7a6944754e url=/mulesoft/current/en-us/gateway/1.12/policies-included-directory.md -->

---
product: Omni Gateway
version: 1.12
---

# Inbound Policies Directory

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## Inbound Policies Included in Flex Gateway

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Policy</th><th>Category</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-agent-card">A2A Agent Card</a></p></td><td><p>A2A</p></td><td><p>Rewrites the Agent Card URL to match the server instance public URL</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-pii-detector">A2A PII Detector</a></p></td><td><p>A2A</p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-prompt-decorator">A2A Prompt Decorator</a></p></td><td><p>A2A</p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-schema-validation">A2A Schema Validation</a></p></td><td><p>A2A</p></td><td><p>Validates Agent requests to ensure they conform to the A2A specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-token-rate-limit">A2A Token Based Rate Limit</a></p></td><td><p>A2A</p></td><td><p>Limits API usage based on the number of GPT-4o-mini tokens consumed by the agents</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-llm-token-rate-limit">LLM Token Based Rate Limit</a></p></td><td><p>LLM</p></td><td><p>Limits Model Proxy usage based on the number of tokens consumed (OpenAI-format APIs)</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-agent-connection-telemetry">Agent Connection Telemetry</a></p></td><td><p>A2A and MCP</p></td><td><p>Tracks the number of requests made to agent or MCP server instances</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-ldap">Basic Authentication: LDAP</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-simple">Basic Authentication: Simple</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-client-id-enforcement">Client ID Enforcement</a></p></td><td><p>Compliance</p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-cors">Cross-Origin Resource Sharing (CORS)</a></p></td><td><p>Compliance</p></td><td><p>Enables access to resources residing in external domains</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-dataweave-body-transformation">DataWeave Body Transformation</a></p></td><td><p>Transformation</p></td><td><p>Transforms request or response body content with a DataWeave script</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-dataweave-headers-transformation">DataWeave Headers Transformation</a></p></td><td><p>Transformation</p></td><td><p>Transforms request or response headers with a DataWeave script</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-dataweave-request-filter">DataWeave Request Filter</a></p></td><td><p>Transformation</p></td><td><p>Filters requests by using a DataWeave script</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-external-authorization">External Authorization</a></p></td><td><p>Security</p></td><td><p>Authenticates requests with an external gRPC or HTTP authorization service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-external-processing">External Processing</a></p></td><td><p>Transformation</p></td><td><p>Sends the incoming HTTP requests or outgoing HTTP responses to an external gRPC service for additional processing</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-header-injection">Header Injection</a></p></td><td><p>Transformation</p></td><td><p>Adds headers to a request or a response</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-header-removal">Header Removal</a></p></td><td><p>Transformation</p></td><td><p>Removes headers from a request or a response</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-health-check">Health Check</a></p></td><td><p>Quality of Service</p></td><td><p>Monitors API upstream health at specific intervals</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-http-caching">HTTP Caching</a></p></td><td><p>Quality of Service</p></td><td><p>Caches HTTP responses from an API implementation</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-injection-protection">Injection Protection</a></p></td><td><p>Security</p></td><td><p>Scans request headers, path, query, and body to protect against SQL, XSS, and custom injection attacks in incoming requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-ip-allowlist">IP Allowlist</a></p></td><td><p>Security</p></td><td><p>Allows a list or range of specified IP addresses to request access</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-ip-blocklist">IP Blocklist</a></p></td><td><p>Security</p></td><td><p>Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-json-threat-protection">JSON Threat Protection</a></p></td><td><p>Security</p></td><td><p>Protects against malicious JSON in API requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-jwt-validation">JWT Validation</a></p></td><td><p>Security</p></td><td><p>Validates a JWT</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-attribute-access-control">MCP Attribute-Based Access Control</a></p></td><td><p>MCP</p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-global-access">MCP Global Access</a></p></td><td><p>MCP</p></td><td><p>Restricts which MCP tools are exposed by defining Allow and Block rules</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-pii-detector">MCP PII Detector</a></p></td><td><p>MCP</p></td><td><p>Blocks elicitation responses containing personally identifiable information (PII) from reaching MCP servers</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-payload-optimization">MCP Payload Optimization</a></p></td><td><p>MCP</p></td><td><p>Optimizes MCP tool responses for token consumption by transforming HTML to Markdown and removing unnecessary data</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-schema-validation">MCP Schema Validation</a></p></td><td><p>MCP</p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-support">MCP Support</a></p></td><td><p>MCP</p></td><td><p>Adds MCP support to a Flex Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-tool-mapping">MCP Tool Mapping</a></p></td><td><p>MCP</p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-message-logging">Message Logging</a></p></td><td><p>Troubleshooting</p></td><td><p>Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-oauth-token-introspection">OAuth 2.0 Token Introspection</a></p></td><td><p>Security</p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-openid-token-enforcement">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td><td><p>Security</p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting">Rate Limiting</a></p></td><td><p>Quality of Service</p></td><td><p>Monitors access to an API by defining the maximum number of requests processed within a period of time</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting-sla">Rate Limiting: SLA-based</a></p></td><td><p>Quality of Service</p></td><td><p>Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-regex-prompt-guard">Regex Prompt Guard</a></p></td><td><p>LLM</p></td><td><p>Blocks LLM requests that match deny-list regex patterns</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-response-timeout">Response Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Set a maximum duration Flex Gateway waits for a response from an upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-schema-validation">Schema Validation</a></p></td><td><p>Security</p></td><td><p>Validates incoming traffic against a supplied OAS3 schema</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-soap-schema-validation">SOAP Schema Validation</a></p></td><td><p>Security</p></td><td><p>Validates incoming traffic against a specified WSDL schema</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-spike-control">Spike Control</a></p></td><td><p>Quality of Service</p></td><td><p>Regulates API traffic</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-sse-logging">SSE Logging</a></p></td><td><p>SSE</p></td><td><p>Logs every SSE event while streaming</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-stream-idle-timeout">Stream Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Set a maximum duration a stream can remain idle without receiving a request or response</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-tracing">Tracing</a></p></td><td><p>Troubleshooting</p></td><td><p>Configure OpenTelemetry distributed tracing for an API</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-traffic-management-route">Traffic Management for Multiple Upstream Services</a></p></td><td><p>Quality of Service</p></td><td><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-traffic-management">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td><td><p>Quality of Service</p></td><td><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint, using weighted percentages</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-tls">Transport Layer Security (TLS) - Inbound</a></p></td><td><p>Security</p></td><td><p>Enables authentication between a client and the API proxy</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-xml-threat-protection">XML Threat Protection</a></p></td><td><p>Security</p></td><td><p>Protects against malicious XML in API requests</p></td></tr></tbody></table>

## See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=804f529280ed88e9c09f856ca4bdb6942069bf52efe75eac81834460906384b8 url=/mulesoft/current/en-us/gateway/1.13/policies-included-directory.md -->

# Inbound Policies Directory

## [](#inbound-policies-included-in-omni-gateway)Inbound Policies Included in Omni Gateway

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Policy</th>
<th class="tableblock halign-left valign-top">Category</th>
<th class="tableblock halign-left valign-top">Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-agent-card" class="xref page">A2A Agent Card</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites the Agent Card URL to match the server instance public URL</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-pii-detector" class="xref page">A2A PII Detector</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in requests sent to the agent</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-prompt-decorator" class="xref page">A2A Prompt Decorator</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Decorates prompts with context information</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-quality-evaluation" class="xref page">A2A Quality Evaluation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates completed A2A agent task responses using an LLM to score quality and completeness</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-schema-validation" class="xref page">A2A Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates Agent requests to ensure they conform to the A2A specification</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-token-rate-limit" class="xref page">A2A Token Based Rate Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits API usage based on the number of GPT-4o-mini tokens consumed by the agents</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-agent-card" class="xref page">A2A v1 Agent Card</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-azure-guardrails" class="xref page">A2A v1 Azure Content Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates A2A v1 agent messages against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-bedrock-guardrails" class="xref page">A2A v1 Bedrock Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-pii-detector" class="xref page">A2A v1 PII Detector</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in A2A v1 requests across all transports</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-prompt-decorator" class="xref page">A2A v1 Prompt Decorator</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Decorates A2A v1 prompts with additional context information</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-schema-validation" class="xref page">A2A v1 Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Verifies that requests to the agent are compliant with the A2A v1.0 specification</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-token-rate-limit" class="xref page">A2A v1 Token Based Rate Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Controls API usage by enforcing token-based rate limits</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-agent-connection-telemetry" class="xref page">Agent Connection Telemetry</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A and MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Tracks the number of requests made to agent or MCP server instances</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-bedrock-guardrails" class="xref page">Amazon Bedrock Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates LLM prompts and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-api-security-identification-header" class="xref page">API Security-Identification Header</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Adds API instance identifiers as response headers for external security platform correlation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-azure-content-safety" class="xref page">Azure Content Safety</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates LLM prompts and responses against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-ldap" class="xref page">Basic Authentication: LDAP</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-simple" class="xref page">Basic Authentication: Simple</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access based on the basic authorization mechanism, with a single user-password</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-client-id-enforcement" class="xref page">Client ID Enforcement</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Compliance</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access only to authorized client applications</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-cors" class="xref page">Cross-Origin Resource Sharing (CORS)</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Compliance</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables access to resources residing in external domains</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-dataweave-body-transformation" class="xref page">DataWeave Body Transformation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transforms request or response body content with a DataWeave script</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-dataweave-headers-transformation" class="xref page">DataWeave Headers Transformation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transforms request or response headers with a DataWeave script</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-dataweave-request-filter" class="xref page">DataWeave Request Filter</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Filters requests by using a DataWeave script</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-external-authorization" class="xref page">External Authorization</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Authenticates requests with an external gRPC or HTTP authorization service</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-external-processing" class="xref page">External Processing</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sends the incoming HTTP requests or outgoing HTTP responses to an external gRPC service for additional processing</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-graphql-introspection-control" class="xref page">GraphQL Introspection Control</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks or allows requests that  access the <code><em>schema</em></code><em>, <code></code></em><code>type</code>, and <code>__typename</code> GraphQL meta fields</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-graphql-operation-limits" class="xref page">GraphQL Operation Limits</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits GraphQL operation depth, aliases, root fields, and directives</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-graphql-schema-validation" class="xref page">GraphQL Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates incoming GraphQL operations against a GraphQL schema definition</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-graphql-static-query-complexity" class="xref page">GraphQL Static Query Complexity</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Calculates query complexity and blocks requests that exceed the defined budget</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-header-injection" class="xref page">Header Injection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Adds headers to a request or a response</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-header-removal" class="xref page">Header Removal</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Removes headers from a request or a response</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-health-check" class="xref page">Health Check</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Monitors API upstream health at specific intervals</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-http-caching" class="xref page">HTTP Caching</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Caches HTTP responses from an API implementation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-injection-protection" class="xref page">Injection Protection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Scans request headers, path, query, and body to protect against SQL, XSS, and custom injection attacks in incoming requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-ip-allowlist" class="xref page">IP Allowlist</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows a list or range of specified IP addresses to request access</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-ip-blocklist" class="xref page">IP Blocklist</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-json-threat-protection" class="xref page">JSON Threat Protection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Protects against malicious JSON in API requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-jwt-validation" class="xref page">JWT Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates a JWT</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-llm-pii-detection" class="xref page">LLM PII Detection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in OpenAI and Anthropic format LLM requests and responses</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-llm-token-rate-limit" class="xref page">LLM Token Based Rate Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits Model Proxy usage based on the number of tokens consumed (OpenAI-format APIs)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control" class="xref page">MCP Attribute-Based Access Control</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-global-access" class="xref page">MCP Global Access</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Restricts which MCP tools are exposed by defining Allow and Block rules</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-pii-detector" class="xref page">MCP PII Detector</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in Model Context Protocol (MCP) JSON-RPC traffic on both the request and response sides</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-payload-optimization" class="xref page">MCP Payload Optimization</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reduces tool response token consumption using one or more configurable methods: remove structural noise, trim oversized responses to match agent intent, or compress repeated structures into TOON</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-progressive-disclosure" class="xref page">MCP Tools Progressive Disclosure</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reduces context window token cost by exposing tools on-demand through search</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-schema-validation" class="xref page">MCP Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates MCP requests to ensure they conform to the MCP specification</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-support" class="xref page">MCP Support</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Adds MCP support to an Omni Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping" class="xref page">MCP Tool Mapping</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-message-logging" class="xref page">Message Logging</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-llm-proxy-request-compression" class="xref page">Model Proxy Request Compression</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Compresses message content and replayed tool results in Model Proxy request bodies before they reach the upstream provider, reducing billed tokens</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-oauth-protected-resource-metadata" class="xref page">OAuth 2.0 Protected Resource Metadata</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Serves OAuth 2.0 Protected Resource Metadata at the well-known endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-oauth-token-introspection" class="xref page">OAuth 2.0 Token Introspection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access only to authorized client applications</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-openid-token-enforcement" class="xref page">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access only to authorized client applications</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting" class="xref page">Rate Limiting</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Monitors access to an API by defining the maximum number of requests processed within a period of time</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting-sla" class="xref page">Rate Limiting: SLA-based</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-regex-prompt-guard" class="xref page">Regex Prompt Guard</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks LLM requests that match deny-list regex patterns</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-response-timeout" class="xref page">Response Idle Timeout</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set a maximum duration Omni Gateway waits for a response from an upstream service</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-schema-validation" class="xref page">Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates incoming traffic against a supplied OAS3 schema</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-soap-schema-validation" class="xref page">SOAP Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates incoming traffic against a specified WSDL schema</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-spike-control" class="xref page">Spike Control</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Regulates API traffic</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-sse-logging" class="xref page">SSE Logging</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs every SSE event while streaming</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-stream-idle-timeout" class="xref page">Stream Idle Timeout</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set a maximum duration a stream can remain idle without receiving a request or response</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-tracing" class="xref page">Tracing</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configure OpenTelemetry distributed tracing for an API</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-traffic-management-route" class="xref page">Traffic Management for Multiple Upstream Services</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-traffic-management" class="xref page">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Manages API instance traffic to multiple upstream services from a single consumer endpoint, using weighted percentages</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-tls" class="xref page">Transport Layer Security (TLS) - Inbound</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables authentication between a client and the API proxy</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-websocket-connection-limit" class="xref page">WebSocket Connection Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits the number of simultaneous WebSocket connections that each API instance allows</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-xml-threat-protection" class="xref page">XML Threat Protection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Protects against malicious XML in API requests</p></td>
</tr>
</tbody>
</table>

## [](#see-also)See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=a01bb6e0e29a80ea436a1c6ceae54fbbeaa905043f84c48c9b3d51be77dcfcaf url=/mulesoft/current/en-us/gateway/1.9/policies-included-directory.md -->

---
product: Omni Gateway
version: 1.9
---

# Inbound Policies Directory

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## Inbound Policies Included in Flex Gateway

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Policy</th><th>Category</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-agent-card">A2A Agent Card</a></p></td><td><p>A2A</p></td><td><p>Rewrites the Agent Card URL to match the server instance public URL</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-pii-detector">A2A PII Detector</a></p></td><td><p>A2A</p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-prompt-decorator">A2A Prompt Decorator</a></p></td><td><p>A2A</p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-a2a-schema-validation">A2A Schema Validation</a></p></td><td><p>A2A</p></td><td><p>Validates Agent requests to ensure they conform to the A2A specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-ldap">Basic Authentication: LDAP</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-simple">Basic Authentication: Simple</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-client-id-enforcement">Client ID Enforcement</a></p></td><td><p>Compliance</p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-cors">Cross-Origin Resource Sharing (CORS)</a></p></td><td><p>Compliance</p></td><td><p>Enables access to resources residing in external domains</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-external-authorization">External Authorization</a></p></td><td><p>Security</p></td><td><p>Authenticates requests with an external gRPC or HTTP authorization service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-external-processing">External Processing</a></p></td><td><p>Transformation</p></td><td><p>Sends the incoming HTTP requests or outgoing HTTP responses to an external gRPC service for additional processing</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-header-injection">Header Injection</a></p></td><td><p>Transformation</p></td><td><p>Adds headers to a request or a response</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-header-removal">Header Removal</a></p></td><td><p>Transformation</p></td><td><p>Removes headers from a request or a response</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-health-check">Health Check</a></p></td><td><p>Quality of Service</p></td><td><p>Monitors API upstream health at specific intervals</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-http-caching">HTTP Caching</a></p></td><td><p>Quality of Service</p></td><td><p>Caches HTTP responses from an API implementation</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-ip-allowlist">IP Allowlist</a></p></td><td><p>Security</p></td><td><p>Allows a list or range of specified IP addresses to request access</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-ip-blocklist">IP Blocklist</a></p></td><td><p>Security</p></td><td><p>Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-json-threat-protection">JSON Threat Protection</a></p></td><td><p>Security</p></td><td><p>Protects against malicious JSON in API requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-jwt-validation">JWT Validation</a></p></td><td><p>Security</p></td><td><p>Validates a JWT</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-mcp-attribute-access-control">MCP Attribute-Based Access Control</a></p></td><td><p>MCP</p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-mcp-schema-validation">MCP Schema Validation</a></p></td><td><p>MCP</p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-mcp-support">MCP Support</a></p></td><td><p>MCP</p></td><td><p>Adds MCP support to a Flex Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-message-logging">Message Logging</a></p></td><td><p>Troubleshooting</p></td><td><p>Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-oauth-token-introspection">OAuth 2.0 Token Introspection</a></p></td><td><p>Security</p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-openid-token-enforcement">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td><td><p>Security</p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting">Rate Limiting</a></p></td><td><p>Quality of Service</p></td><td><p>Monitors access to an API by defining the maximum number of requests processed within a period of time</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting-sla">Rate Limiting: SLA-based</a></p></td><td><p>Quality of Service</p></td><td><p>Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-response-timeout">Response Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Set a maximum duration Flex Gateway waits for a response from an upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-schema-validation">Schema Validation</a></p></td><td><p>Security</p></td><td><p>Validates incoming traffic against a supplied OAS3 schema</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-spike-control">Spike Control</a></p></td><td><p>Quality of Service</p></td><td><p>Regulates API traffic</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-sse-logging">SSE Logging</a></p></td><td><p>SSE</p></td><td><p>Logs every SSE event while streaming</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-stream-idle-timeout">Stream Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Set a maximum duration a stream can remain idle without receiving a request or response</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-traffic-management-route">Traffic Management for Multiple Upstream Services</a></p></td><td><p>Quality of Service</p></td><td><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-traffic-management">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td><td><p>Quality of Service</p></td><td><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint, using weighted percentages</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-tls">Transport Layer Security (TLS) - Inbound</a></p></td><td><p>Security</p></td><td><p>Enables authentication between a client and the API proxy</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound">Transport Layer Security (TLS) - Outbound</a></p></td><td><p>Security</p></td><td><p>Enables two-way authentication between the API proxy and an upstream service</p></td></tr></tbody></table>

## See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=68c80d80cd3c07310aaae7d74e0955877554e3c54d427cfc808fc06b0fdf36da url=/mulesoft/current/en-us/gateway/latest/policies-included-directory.md -->

# Inbound Policies Directory

## [](#inbound-policies-included-in-omni-gateway)Inbound Policies Included in Omni Gateway

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Policy</th>
<th class="tableblock halign-left valign-top">Category</th>
<th class="tableblock halign-left valign-top">Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-agent-card" class="xref page">A2A Agent Card</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites the Agent Card URL to match the server instance public URL</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-pii-detector" class="xref page">A2A PII Detector</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in requests sent to the agent</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-prompt-decorator" class="xref page">A2A Prompt Decorator</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Decorates prompts with context information</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-quality-evaluation" class="xref page">A2A Quality Evaluation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates completed A2A agent task responses using an LLM to score quality and completeness</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-schema-validation" class="xref page">A2A Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates Agent requests to ensure they conform to the A2A specification</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-token-rate-limit" class="xref page">A2A Token Based Rate Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits API usage based on the number of GPT-4o-mini tokens consumed by the agents</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-agent-card" class="xref page">A2A v1 Agent Card</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-azure-guardrails" class="xref page">A2A v1 Azure Content Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates A2A v1 agent messages against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-bedrock-guardrails" class="xref page">A2A v1 Bedrock Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-pii-detector" class="xref page">A2A v1 PII Detector</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in A2A v1 requests across all transports</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-prompt-decorator" class="xref page">A2A v1 Prompt Decorator</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Decorates A2A v1 prompts with additional context information</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-schema-validation" class="xref page">A2A v1 Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Verifies that requests to the agent are compliant with the A2A v1.0 specification</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-token-rate-limit" class="xref page">A2A v1 Token Based Rate Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Controls API usage by enforcing token-based rate limits</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-agent-connection-telemetry" class="xref page">Agent Connection Telemetry</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A2A and MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Tracks the number of requests made to agent or MCP server instances</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-bedrock-guardrails" class="xref page">Amazon Bedrock Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates LLM prompts and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-api-security-identification-header" class="xref page">API Security-Identification Header</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Adds API instance identifiers as response headers for external security platform correlation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-azure-content-safety" class="xref page">Azure Content Safety</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates LLM prompts and responses against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-ldap" class="xref page">Basic Authentication: LDAP</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple" class="xref page">Basic Authentication: Simple</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access based on the basic authorization mechanism, with a single user-password</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-client-id-enforcement" class="xref page">Client ID Enforcement</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Compliance</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access only to authorized client applications</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-cors" class="xref page">Cross-Origin Resource Sharing (CORS)</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Compliance</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables access to resources residing in external domains</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-crowdstrike-aidr-guardrails" class="xref page">CrowdStrike AIDR Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates OpenAI-format LLM prompts and responses against CrowdStrike Falcon AI Detection and Response (AIDR), rejecting or redacting flagged content</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-dataweave-body-transformation" class="xref page">DataWeave Body Transformation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transforms request or response body content with a DataWeave script</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-dataweave-headers-transformation" class="xref page">DataWeave Headers Transformation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transforms request or response headers with a DataWeave script</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-dataweave-request-filter" class="xref page">DataWeave Request Filter</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Filters requests by using a DataWeave script</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-external-authorization" class="xref page">External Authorization</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Authenticates requests with an external gRPC or HTTP authorization service</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-external-processing" class="xref page">External Processing</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sends the incoming HTTP requests or outgoing HTTP responses to an external gRPC service for additional processing</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-f5-guardrails" class="xref page">F5 Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates LLM prompts and responses against F5 AI Guardrails, blocking, flagging, or redacting flagged content</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-google-model-armor-guardrails" class="xref page">Google Model Armor Guardrails</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Evaluates OpenAI and Gemini format LLM prompts and responses against a Google Cloud Model Armor template, blocking or redacting flagged content</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-graphql-access-control" class="xref page">GraphQL Access Control</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Authorizes incoming GraphQL requests by evaluating Cedar rules</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-graphql-introspection-control" class="xref page">GraphQL Introspection Control</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks or allows requests that  access the <code><em>schema</em></code><em>, <code></code></em><code>type</code>, and <code>__typename</code> GraphQL meta fields</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-graphql-operation-limits" class="xref page">GraphQL Operation Limits</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits GraphQL operation depth, aliases, root fields, and directives</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-graphql-schema-validation" class="xref page">GraphQL Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates incoming GraphQL operations against a GraphQL schema definition</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-graphql-static-query-complexity" class="xref page">GraphQL Static Query Complexity</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">GraphQL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Calculates query complexity and blocks requests that exceed the defined budget</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-header-injection" class="xref page">Header Injection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Adds headers to a request or a response</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-header-removal" class="xref page">Header Removal</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Removes headers from a request or a response</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-health-check" class="xref page">Health Check</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Monitors API upstream health at specific intervals</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-http-caching" class="xref page">HTTP Caching</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Caches HTTP responses from an API implementation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-injection-protection" class="xref page">Injection Protection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Scans request headers, path, query, and body to protect against SQL, XSS, and custom injection attacks in incoming requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-ip-allowlist" class="xref page">IP Allowlist</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows a list or range of specified IP addresses to request access</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-ip-blocklist" class="xref page">IP Blocklist</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-javascript-scripting" class="xref page">JavaScript Scripting</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transformation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Runs a user-supplied JavaScript module to inspect and modify requests and responses</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-json-threat-protection" class="xref page">JSON Threat Protection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Protects against malicious JSON in API requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation" class="xref page">JWT Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates a JWT</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-llm-pii-detection" class="xref page">LLM PII Detection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in OpenAI and Anthropic format LLM requests and responses</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-llm-token-rate-limit" class="xref page">LLM Token Based Rate Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits Model Proxy usage based on the number of tokens consumed (OpenAI-format APIs)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control" class="xref page">MCP Attribute-Based Access Control</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access" class="xref page">MCP Global Access</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Restricts which MCP tools are exposed by defining Allow and Block rules</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-pii-detector" class="xref page">MCP PII Detector</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks elicitation responses containing personally identifiable information (PII) from reaching MCP servers</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-payload-optimization" class="xref page">MCP Payload Optimization</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reduces tool response token consumption using one or more configurable methods: remove structural noise, trim oversized responses to match agent intent, or compress repeated structures into TOON</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-progressive-disclosure" class="xref page">MCP Tools Progressive Disclosure</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reduces context window token cost by exposing tools on-demand through search</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-schema-validation" class="xref page">MCP Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates MCP requests to ensure they conform to the MCP specification</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support" class="xref page">MCP Support</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Adds MCP support to an Omni Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping" class="xref page">MCP Tool Mapping</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-message-logging" class="xref page">Message Logging</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-llm-proxy-request-compression" class="xref page">Model Proxy Request Compression</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Compresses message content and replayed tool results in Model Proxy request bodies before they reach the upstream provider, reducing billed tokens</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-oauth-protected-resource-metadata" class="xref page">OAuth 2.0 Protected Resource Metadata</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Serves OAuth 2.0 Protected Resource Metadata at the well-known endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-oauth-token-introspection" class="xref page">OAuth 2.0 Token Introspection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access only to authorized client applications</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-openid-token-enforcement" class="xref page">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows access only to authorized client applications</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting" class="xref page">Rate Limiting</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Monitors access to an API by defining the maximum number of requests processed within a period of time</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting-sla" class="xref page">Rate Limiting: SLA-based</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-regex-prompt-guard" class="xref page">Regex Prompt Guard</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LLM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks LLM requests that match deny-list regex patterns</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-response-timeout" class="xref page">Response Idle Timeout</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set a maximum duration Omni Gateway waits for a response from an upstream service</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-schema-validation" class="xref page">Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates incoming traffic against a supplied OAS3 schema</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-soap-schema-validation" class="xref page">SOAP Schema Validation</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates incoming traffic against a specified WSDL schema</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-spike-control" class="xref page">Spike Control</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Regulates API traffic</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-sse-logging" class="xref page">SSE Logging</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs every SSE event while streaming</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-stream-idle-timeout" class="xref page">Stream Idle Timeout</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set a maximum duration a stream can remain idle without receiving a request or response</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-tracing" class="xref page">Tracing</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configure OpenTelemetry distributed tracing for an API</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management-route" class="xref page">Traffic Management for Multiple Upstream Services</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management" class="xref page">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Manages API instance traffic to multiple upstream services from a single consumer endpoint, using weighted percentages</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-tls" class="xref page">Transport Layer Security (TLS) - Inbound</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables authentication between a client and the API proxy</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-websocket-connection-limit" class="xref page">WebSocket Connection Limit</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Quality of Service</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Limits the number of simultaneous WebSocket connections that each API instance allows</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-web-services-security" class="xref page">WS-Security</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Validates Web Services Security (WS-Security) UsernameToken credentials, XML signatures, or both on inbound SOAP requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/gateway/latest/policies-included-xml-threat-protection" class="xref page">XML Threat Protection</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Protects against malicious XML in API requests</p></td>
</tr>
</tbody>
</table>

## [](#see-also)See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=cb08326eeacce12beff4c653521ac6296a01503219a859f6f6bac6b5aca5f411 url=/mulesoft/current/en-us/gateway/1.12/policies-included-injection-protection.md -->

---
product: Omni Gateway
version: 1.12
keywords: sql injection, xss, injection protection, api gateway, flex gateway, gateway, policy
---

# Injection Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Injection Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Scans incoming requests to protect against SQL, XSS, and custom injection attacks</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - Bad Request</p></td></tr></tbody></table>

## Summary

The Injection Protection policy scans incoming request headers, path, query string, and body for SQL
injection, XSS (Cross-Site Scripting), and custom injection attacks. The policy provides built-in
protections againt SQL and XSS attacks. Configure custom protections by defining regex patterns that
the policy should scan for.

The policy checks the request against the enabled built-in and custom rules. Depending on wether
**Reject Requests** is enabled, the policy either:

- Rejects the request and returns `400` (Bad Request) with the added response header
  `x-injection-protection: blocked`.

- Allows the request to reach the backend service and logs a policy violation.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: injection-protection-flex config: builtInProtections: \["sql", "xss"\] //
REQUIRED: include "sql", "xss", or both customProtections: \[\] // OPTIONAL: list of { name:
<string>, regex: <string> } protectPathAndQuery: <bool> // REQUIRED protectHeaders: <bool> //
REQUIRED protectBody: <bool> // REQUIRED headersToProtect: <string> // OPTIONAL, default: "" (empty
= all headers) rejectRequests: <bool> // REQUIRED: true = reject with 400, false = allow and log

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>builtInProtections</code></p></div></div></td><td><div><div><p>Yes (at least one protection required)</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>The built-in protection types to enable. Valid values are <code>"sql"</code>, <code>"xss"</code>, or both. SQL protection detects patterns such as tautologies (for example, <code>OR 1=1</code>), comment-based injection (<code>--</code>, <code>#</code>), union/select statements, and keywords such as <code>DROP</code> and <code>DELETE</code>. XSS protection detects patterns such as script and iframe tags, event handlers, and common script schemes.</p></div></div></td></tr><tr><td><div><div><p><code>customProtections</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div></div></td><td><div><div><p>Custom protection rules for application-specific injection types. Each rule requires a <code>name</code> and a <code>regex</code> pattern. Values must be valid and not empty.</p></div></div></td></tr><tr><td><div><div><p><code>protectPathAndQuery</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks the request path and query string. The policy applies URL decoding to the path and query before matching.</p></div></div></td></tr><tr><td><div><div><p><code>protectHeaders</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks request headers. <code>headersToProtect</code> specifies which headers the policy checks.</p></div></div></td></tr><tr><td><div><div><p><code>headersToProtect</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>"" (empty)</p></div></div></td><td><div><div><p>A case-insensitive, comma-separated list of header names to check. If the value is empty, the policy checks all headers. This parameter is ignored if <code>protectHeaders</code> is <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>protectBody</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks the request body for injection patterns.</p></div></div></td></tr><tr><td><div><div><p><code>rejectRequests</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the gateway rejects matching requests with a <code>400</code> response code and a JSON error message. If <code>false</code>, the gateway allows matching requests and logs a warning.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: injection-protection-flex config: builtInProtections: \["sql", "xss"\]
customProtections: \[\] protectPathAndQuery: true protectHeaders: true headersToProtect:
"referer,user-agent" protectBody: true rejectRequests: true

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Built-in Protections</p></div></div></td><td><div><div><p>The built-in SQL and XSS injection protection settings.</p></div></div></td></tr><tr><td><div><div><p>Custom Protections</p></div></div></td><td><div><div><p>The rules defined with a name and regex pattern for custom injection types.</p></div></div></td></tr><tr><td><div><div><p>Protect Path and Query</p></div></div></td><td><div><div><p>If enabled, the gateway checks the request path and query string.</p></div></div></td></tr><tr><td><div><div><p>Protect Headers</p></div></div></td><td><div><div><p>If enadbled, the gateway checks the request headers.</p></div></div></td></tr><tr><td><div><div><p>Headers to Protect</p></div></div></td><td><div><div><p>List of header names to check. Leave empty to check all headers.</p></div></div></td></tr><tr><td><div><div><p>Protect Body</p></div></div></td><td><div><div><p>If enabled, the gateway checks the request body.</p></div></div></td></tr><tr><td><div><div><p>Reject Requests</p></div></div></td><td><div><div><p>If enabled, the gateway rejects matching requests with a <code>400</code> response code. Otherwise, the gateway allows them to reach the upstream service and logs a policy violation.</p></div></div></td></tr></tbody></table>

<!-- document id=3b047063ff45d7bde723a26e8f1208794e641e3861ca9b7510b312fc96c3dc61 url=/mulesoft/current/en-us/gateway/1.13/policies-included-injection-protection.md -->

---
product: Omni Gateway
version: 1.13
keywords: sql injection, xss, injection protection, api gateway, flex gateway, gateway, policy
---

# Injection Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Injection Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Scans incoming requests to protect against SQL, XSS, and custom injection attacks</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/injection-protection-release-notes">Injection Protection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - Bad Request</p></td></tr></tbody></table>

## Summary

The Injection Protection policy scans incoming request headers, path, query string, and body for SQL
injection, XSS (Cross-Site Scripting), and custom injection attacks. The policy provides built-in
protections againt SQL and XSS attacks. Configure custom protections by defining regex patterns that
the policy should scan for.

The policy checks the request against the enabled built-in and custom rules. Depending on wether
**Reject Requests** is enabled, the policy either:

- Rejects the request and returns `400` (Bad Request) with the added response header
  `x-injection-protection: blocked`.

- Allows the request to reach the backend service and logs a policy violation.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: injection-protection-flex config: builtInProtections: \["sql", "xss"\] //
REQUIRED: include "sql", "xss", or both customProtections: \[\] // OPTIONAL: list of { name:
<string>, regex: <string> } protectPathAndQuery: <bool> // REQUIRED protectHeaders: <bool> //
REQUIRED protectBody: <bool> // REQUIRED headersToProtect: <string> // OPTIONAL, default: "" (empty
= all headers) rejectRequests: <bool> // REQUIRED: true = reject with 400, false = allow and log

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>builtInProtections</code></p></div></div></td><td><div><div><p>Yes (at least one protection required)</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>The built-in protection types to enable. Valid values are <code>"sql"</code>, <code>"xss"</code>, or both. SQL protection detects patterns such as tautologies (for example, <code>OR 1=1</code>), comment-based injection (<code>--</code>, <code>#</code>), union/select statements, and keywords such as <code>DROP</code> and <code>DELETE</code>. XSS protection detects patterns such as script and iframe tags, event handlers, and common script schemes.</p></div></div></td></tr><tr><td><div><div><p><code>customProtections</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div></div></td><td><div><div><p>Custom protection rules for application-specific injection types. Each rule requires a <code>name</code> and a <code>regex</code> pattern. Values must be valid and not empty.</p></div></div></td></tr><tr><td><div><div><p><code>protectPathAndQuery</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks the request path and query string. The policy applies URL decoding to the path and query before matching.</p></div></div></td></tr><tr><td><div><div><p><code>protectHeaders</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks request headers. <code>headersToProtect</code> specifies which headers the policy checks.</p></div></div></td></tr><tr><td><div><div><p><code>headersToProtect</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>"" (empty)</p></div></div></td><td><div><div><p>A case-insensitive, comma-separated list of header names to check. If the value is empty, the policy checks all headers. This parameter is ignored if <code>protectHeaders</code> is <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>protectBody</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks the request body for injection patterns.</p></div></div></td></tr><tr><td><div><div><p><code>rejectRequests</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the gateway rejects matching requests with a <code>400</code> response code and a JSON error message. If <code>false</code>, the gateway allows matching requests and logs a warning.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: injection-protection-flex config: builtInProtections: \["sql", "xss"\]
customProtections: \[\] protectPathAndQuery: true protectHeaders: true headersToProtect:
"referer,user-agent" protectBody: true rejectRequests: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Built-in Protections</p></div></div></td><td><div><div><p>The built-in SQL and XSS injection protection settings.</p></div></div></td></tr><tr><td><div><div><p>Custom Protections</p></div></div></td><td><div><div><p>The rules defined with a name and regex pattern for custom injection types.</p></div></div></td></tr><tr><td><div><div><p>Protect Path and Query</p></div></div></td><td><div><div><p>If enabled, the gateway checks the request path and query string.</p></div></div></td></tr><tr><td><div><div><p>Protect Headers</p></div></div></td><td><div><div><p>If enadbled, the gateway checks the request headers.</p></div></div></td></tr><tr><td><div><div><p>Headers to Protect</p></div></div></td><td><div><div><p>List of header names to check. Leave empty to check all headers.</p></div></div></td></tr><tr><td><div><div><p>Protect Body</p></div></div></td><td><div><div><p>If enabled, the gateway checks the request body.</p></div></div></td></tr><tr><td><div><div><p>Reject Requests</p></div></div></td><td><div><div><p>If enabled, the gateway rejects matching requests with a <code>400</code> response code. Otherwise, the gateway allows them to reach the upstream service and logs a policy violation.</p></div></div></td></tr></tbody></table>

<!-- document id=20ae36665f39d3c96dbf15d92c76698de43a770d545d981e7e4d978db0106671 url=/mulesoft/current/en-us/gateway/latest/policies-included-injection-protection.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: sql injection, xss, injection protection, api gateway, flex gateway, gateway, policy
---

# Injection Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Injection Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Scans incoming requests to protect against SQL, XSS, and custom injection attacks</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/injection-protection-release-notes">Injection Protection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>400</code> - Bad Request</p></td></tr></tbody></table>

## Summary

The Injection Protection policy scans incoming request headers, path, query string, and body for SQL
injection, XSS (Cross-Site Scripting), and custom injection attacks. The policy provides built-in
protections againt SQL and XSS attacks. Configure custom protections by defining regex patterns that
the policy should scan for.

The policy checks the request against the enabled built-in and custom rules. Depending on wether
**Reject Requests** is enabled, the policy either:

- Rejects the request and returns `400` (Bad Request) with the added response header
  `x-injection-protection: blocked`.

- Allows the request to reach the backend service and logs a policy violation.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: injection-protection-flex config: builtInProtections: \["sql", "xss"\] //
REQUIRED: include "sql", "xss", or both customProtections: \[\] // OPTIONAL: list of { name:
<string>, regex: <string> } protectPathAndQuery: <bool> // REQUIRED protectHeaders: <bool> //
REQUIRED protectBody: <bool> // REQUIRED headersToProtect: <string> // OPTIONAL, default: "" (empty
= all headers) rejectRequests: <bool> // REQUIRED: true = reject with 400, false = allow and log

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>builtInProtections</code></p></div></div></td><td><div><div><p>Yes (at least one protection required)</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>The built-in protection types to enable. Valid values are <code>"sql"</code>, <code>"xss"</code>, or both. SQL protection detects patterns such as tautologies (for example, <code>OR 1=1</code>), comment-based injection (<code>--</code>, <code>#</code>), union/select statements, and keywords such as <code>DROP</code> and <code>DELETE</code>. XSS protection detects patterns such as script and iframe tags, event handlers, and common script schemes.</p></div></div></td></tr><tr><td><div><div><p><code>customProtections</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div></div></td><td><div><div><p>Custom protection rules for application-specific injection types. Each rule requires a <code>name</code> and a <code>regex</code> pattern. Values must be valid and not empty.</p></div></div></td></tr><tr><td><div><div><p><code>protectPathAndQuery</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks the request path and query string. The policy applies URL decoding to the path and query before matching.</p></div></div></td></tr><tr><td><div><div><p><code>protectHeaders</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks request headers. <code>headersToProtect</code> specifies which headers the policy checks.</p></div></div></td></tr><tr><td><div><div><p><code>headersToProtect</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>"" (empty)</p></div></div></td><td><div><div><p>A case-insensitive, comma-separated list of header names to check. If the value is empty, the policy checks all headers. This parameter is ignored if <code>protectHeaders</code> is <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>protectBody</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the policy checks the request body for injection patterns.</p></div></div></td></tr><tr><td><div><div><p><code>rejectRequests</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>If <code>true</code>, the gateway rejects matching requests with a <code>400</code> response code and a JSON error message. If <code>false</code>, the gateway allows matching requests and logs a warning.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: injection-protection-flex config: builtInProtections: \["sql", "xss"\]
customProtections: \[\] protectPathAndQuery: true protectHeaders: true headersToProtect:
"referer,user-agent" protectBody: true rejectRequests: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Built-in Protections</p></div></div></td><td><div><div><p>The built-in SQL and XSS injection protection settings.</p></div></div></td></tr><tr><td><div><div><p>Custom Protections</p></div></div></td><td><div><div><p>The rules defined with a name and regex pattern for custom injection types.</p></div></div></td></tr><tr><td><div><div><p>Protect Path and Query</p></div></div></td><td><div><div><p>If enabled, the gateway checks the request path and query string.</p></div></div></td></tr><tr><td><div><div><p>Protect Headers</p></div></div></td><td><div><div><p>If enadbled, the gateway checks the request headers.</p></div></div></td></tr><tr><td><div><div><p>Headers to Protect</p></div></div></td><td><div><div><p>List of header names to check. Leave empty to check all headers.</p></div></div></td></tr><tr><td><div><div><p>Protect Body</p></div></div></td><td><div><div><p>If enabled, the gateway checks the request body.</p></div></div></td></tr><tr><td><div><div><p>Reject Requests</p></div></div></td><td><div><div><p>If enabled, the gateway rejects matching requests with a <code>400</code> response code. Otherwise, the gateway allows them to reach the upstream service and logs a policy violation.</p></div></div></td></tr></tbody></table>

<!-- document id=06d41a3da04142b3ca457ec7973c8700fd164ca3904eb77221f6002437bdd393 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-istio.md -->

---
product: Omni Gateway
version: 1.12
---

# Integrating Flex Gateway with Istio Service Mesh

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To leverage Flex Gateway policies, logging, and metrics from the Anypoint Platform control plane,
integrate Flex Gateway into your Istio Service Mesh. Deploy Flex Gateway as an ingress gateway to
manage ingress north-south cluster traffic and internal east-west traffic inside the cluster.

To integrate Flex Gateway, use the following architecture diagram and tutorial. Flex Gateway is
integrated by using a modified version of the
[Istio Bookinfo sample application](https://istio.io/latest/docs/examples/bookinfo/). In the Flex
Gateway integration:

- An Istio virtual service forwards all ingress north-south traffic to Flex Gateway.

- Direct access to the `bookinfo` name space is restricted. All external traffic into the `bookinfo`
  namespace must come from the `flex` namespace. Istio automatically configures mTLS configuration
  between the `bookinfo` and `flex`.

- Flex Gateway protects and monitors the exposed product page service from ingress traffic with an
  API instance.

- The Istio sidecar intercepts east-west traffic between the product page service and the reviews
  service. Flex Gateway acts as an ingress gateway managing incoming traffic to the reviews service.

![A diagram demonstrating the architecture to integrate Flex Gateway with Istio](/mulesoft/current/en-us/gateway/1.12/_images/flex-istio-deployment.png)

> [!NOTE] In the diagram, Flex Gateway is running in Connected Mode. If Flex Gateway runs in Local
> Mode, the Anypoint Platform control plane is absent.

To configure the architecture:

1.  [Complete Before You Begin](#before-you-begin).

2.  [Set up your environment](#setup-environment).

3.  [Intercept ingress north-south traffic](#forward-ingress-traffic).

4.  [Intercept east-west traffic between services](#create-a-service).

## Before You Begin

Before you begin, install the following prerequisites:

- [Docker](https://docs.docker.com/get-docker/)

- [Download Flex Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-install#kubernetes)

- [K3d](https://k3d.io/v5.0.0/#installation) to create a Kubernetes cluster inside of docker

- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) to control the Kubernetes cluster

- [Helm](https://helm.sh/docs/intro/install/) to install Flex Gateway and Istio

## Set up Environment

1.  Create a Kubernetes cluster for this demo or skip this step if you already have a cluster you
    want to use:

    ```ssh
    k3d cluster create demo-istio --k3s-arg "--disable=traefik@server:0" --port '80:80@server:0' --port '443:443@server:0'
    ```

2.  Add the Flex Gateway and Istio Helm repositories:

    ```ssh
    helm repo add istio https://istio-release.storage.googleapis.com/charts \
    && helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm \
    && helm repo up
    ```

3.  Install Istio:

    1.  Install the Istio base chart that contains the cluster-wide Custom Resource Definitions
        (CRDs) that must be installed before deploying the Istio control plane:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-base istio/base --version 1.21.2 --set defaultRevision=default
        ```

    2.  Install the Istio discovery chart that deploys the `istiod` service:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istiod istio/istiod --version 1.21.2
        ```

    3.  Install an Istio ingress gateway:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-ingress istio/gateway --version 1.21.2
        ```

4.  Install Flex Gateway:

    1.  Create the namespace and set up the label to enable the sidecar injection:

        ```ssh
        kubectl create ns flex && kubectl label ns flex istio-injection=enabled --overwrite
        ```

    2.  Install Flex Gateway:

        ```ssh
        helm upgrade -i --wait -n flex --version 1.7.0 flex flex-gateway/flex-gateway \
        --set gateway.scope=Namespace \
        --set gateway.mode=connected \
        --set service.type=ClusterIP \
        --set service.http.port=8081 \
        --set service.https.enabled=false \
        --set-file registration.content=registration.yaml
        ```

    3.  List all services and API instances previously created:

        ```ssh
        kubectl -n flex get svc
        ```

5.  Install the `bookinfo` application:

    1.  Enable Istio label injection in the default namespace and install the `bookinfo`
        application:

        ```ssh
        kubectl create ns bookinfo \
        && kubectl label ns bookinfo istio-injection=enabled --overwrite \
        && kubectl -n bookinfo apply -l version!=v2,version!=v3 -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/bookinfo/platform/kube/bookinfo.yaml
        ```

    2.  Check the pod status:

        ```ssh
        kubectl -n bookinfo get pods
        ```

6.  Install the `sleep` application to test traffic:

    1.  Create the `test` namespace and install the `sleep` application:

        ```ssh
        kubectl create ns test \
        && kubectl label ns test istio-injection=enabled --overwrite \
        && kubectl -n test apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/sleep/sleep.yaml
        ```

    2.  Check the status of the pods:

        ```ssh
        kubectl -n test get pods
        ```

## Intercept Ingress North-South Traffic

Intercept ingress north-south traffic to protect services from external traffic.

To intercept ingress north-south traffic:

1.  Create the Flex Gateway ingress API instance to forward all ingress north-south traffic in the
    `bookinfo` namespace to the `productpage` service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: ingress
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/ingress/
        services:
          productpage:
            address: http://productpage.bookinfo.svc:9080
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with the following downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/ingress/`

        Configure the API instance with the following upstream parameters:

      - **Route label**: `productpage`

      - **Upstream URL**:
        `[http://productpage.bookinfo.svc:9080](http://productpage.bookinfo.svc:9080)`

2.  Create the `flex` Istio ingress gateway to forward the ingress traffic to Flex Gateway using a
    Istio virtual service:

    1.  Create the Flex Gateway:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: Gateway
        metadata:
          name: flex
          namespace: flex
        spec:
          selector:
            app: istio-ingress
          servers:
          - port:
              number: 80
              name: http
              protocol: HTTP
            hosts:
            - "*"
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: flex
          namespace: flex
        spec:
          hosts:
          - "*"
          gateways:
          - flex
          http:
          - route:
            - destination:
                host: flex
                port:
                  number: 8081
            rewrite:
              uri: /ingress/
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request to the `/api/v1/products/1`
        page:

        ```ssh
        curl -v http://localhost/api/v1/products/1
        ```

    3.  Ensure you receive this output:

        ```ssh
        < HTTP/1.1 200 OK
        < server: istio-envoy
        < date: Tue, 27 Feb 2024 22:06:33 GMT
        < content-type: application/json
        < content-length: 195
        < x-envoy-upstream-service-time: 8
        <
        * Connection #0 to host localhost left intact
        {"id": 2, "author": "William Shakespeare", "year": 1595, "type": "paperback", "pages": 200, "publisher": "PublisherA", "language": "English", "ISBN-10": "1234567890", "ISBN-13": "123-1234567890"}
        ```

3.  Protect the Flex Gateway API instance by applying the Basic Authentication policy:

    1.  Add the policy:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: ingress
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/ingress/
          services:
            productpage:
              address: http://productpage.bookinfo.svc:9080
          policies:
          - policyRef:
              name: http-basic-authentication-flex
            config:
              username: user1
              password: password1
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request:

        ```ssh
        curl -v http://localhost/
        ```

    3.  Make sure you receive a `401` response.

4.  Add the Message Logging policy to log traffic:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: ApiInstance
    metadata:
      name: ingress
      namespace: flex
    spec:
      address: http://0.0.0.0:8081/ingress/
      services:
        productpage:
          address: http://productpage.bookinfo.svc:9080
      policies:
      - policyRef:
          name: http-basic-authentication-flex
        config:
          username: user1
          password: password1
      - policyRef:
          name: message-logging-flex
        config:
          loggingConfiguration:
          - itemName: "Request"
            itemData:
              message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
              level: "INFO"
              firstSection: true
          - itemName: "Response"
            itemData:
              message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
              level: "INFO"
              secondSection: true
        order: 0
    EOF
    ```

## Intercept East-West Traffic Between Services

Use Flex Gateway to intercept east-west traffic between services and protect them with policies.

To intercept east-west traffic:

1.  Create the `bookinfo-reviews` API instance to forward the east-west traffic to the `reviews`
    service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: bookinfo-reviews
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/bookinfo/reviews/
        services:
          upstream:
            address: http://reviews.bookinfo.svc:9080
        policies:
        - policyRef:
            name: message-logging-flex
          config:
            loggingConfiguration:
            - itemName: "Request"
              itemData:
                message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                level: "INFO"
                firstSection: true
            - itemName: "Response"
              itemData:
                message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                level: "INFO"
                secondSection: true
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with these downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/bookinfo/reviews/`

        Configure the API instance with these upstream parameters:

      - **Route label**: `reviews`

      - **Upstream URL**: `[http://reviews.bookinfo.svc:9080](http://reviews.bookinfo.svc:9080)`

2.  Intercept the traffic between the `productpage` service and the `reviews` service and forward it
    to the `flex` service:

    1.  Create the Istio API instance:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: bookinfo-reviews
          namespace: istio-system
        spec:
          hosts:
          - reviews.bookinfo.svc.cluster.local
          http:
          - match:
            - sourceLabels:
                app: flex
            route:
            - destination:
                host: reviews.bookinfo.svc.cluster.local
                port:
                  number: 9080
          - route:
            - destination:
                host: flex.flex.svc.cluster.local
                port:
                  number: 8081
            rewrite:
              uri: /bookinfo/reviews/
        EOF
        ```

    2.  Send a test request with the `user1` username and `password1` password to the
        `/productpage`:

        ```ssh
        curl -v -u user1:password1 http://localhost/productpage
        ```

    3.  Check the Flex Gateway logs to ensure the request sent from the `productpage` service to the
        `reviews` service passed through Flex Gateway. The logs appear similar to:

        ```ssh
        [flex-gateway-envoy][info] wasm log productpage-message-logging-flex-2.flex.productpage.flex.svc main: [policy: productpage-message-logging-flex-2.flex][api: productpage.flex.svc][req: 6e1f7c32-918d-4b6a-af3f-36a4430f80ae] [accessLog] > HTTP/1.1 GET localhost/ingress/productpage
        [flex-gateway-envoy][info] wasm log bookinfo-reviews-message-logging-flex-1.flex.bookinfo-reviews.flex.svc main: [policy: bookinfo-reviews-message-logging-flex-1.flex][api: bookinfo-reviews.flex.svc][req: b23e9c64-a2aa-4464-8984-d1dd6c18f7ea] [accessLog] > HTTP/1.1 GET reviews:9080/bookinfo/reviews/reviews/0
        ```

        > [!NOTE] Use the standard output logs for a quick log check. To learn how to view standard
        > output logs, see [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.12/flex-local-view-logs).

    4.  Apply the Rate Limiting policy to the `bookinfo-reviews` API instance to protect the
        `reviews` service:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: bookinfo-reviews
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/bookinfo/reviews/
          services:
            upstream:
              address: http://reviews.bookinfo.svc:9080
          policies:
          - policyRef:
              name: message-logging-flex
            config:
              loggingConfiguration:
              - itemName: "Request"
                itemData:
                  message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                  level: "INFO"
                  firstSection: true
              - itemName: "Response"
                itemData:
                  message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                  level: "INFO"
                  secondSection: true
            order: 0
          - policyRef:
              name: rate-limiting-flex
            config:
              rateLimits:
              - timePeriodInMilliseconds: 60000
                maximumRequests: 2
              exposeHeaders: true
        EOF
        ```

3.  Restrict direct access to the `bookinfo` service:

    1.  Restrict access:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: security.istio.io/v1
        kind: AuthorizationPolicy
        metadata:
          name: flex-allow
          namespace: bookinfo
        spec:
          action: ALLOW
          rules:
          - from:
            - source:
                namespaces:
                - flex
                - bookinfo
        EOF
        ```

    2.  Send a test request from the test namespace to the `details` service:

        ```ssh
        kubectl -n test exec -ti -c sleep $(kubectl -n test get pod --no-headers -o=name) -- curl -v details.bookinfo:9080/details/0
        ```

    3.  Make sure you receive this `403 forbidden` response:

        ```ssh
        < HTTP/1.1 403 Forbidden
        < content-length: 19
        < content-type: text/plain
        < date: Thu, 09 May 2024 15:51:11 GMT
        < server: envoy
        < x-envoy-upstream-service-time: 0
        <
        * Connection #0 to host details.bookinfo left intact
        RBAC: access denied
        ```

    4.  Send this request to the `details` service to find out how to access the `bookinfo` service
        from the `flex` namespace:

        ```ssh
        kubectl -n flex exec -ti -c app  $(kubectl -n flex get pod --no-headers -o=name) -- flexctl check http http://details.bookinfo:9080/details/0
        ```

    5.  Make sure you receive this response:

        ```ssh
        [flexctl][info] Access to http address 'http://details.bookinfo:9080/details/0': ok
        ```

<!-- document id=2b7b41e84803ece129e500df2b1ecc4f87ceb2ae5d055ed2a5efb8fa28da5106 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-istio.md -->

---
product: Omni Gateway
version: 1.9
---

# Integrating Flex Gateway with Istio Service Mesh

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To leverage Flex Gateway policies, logging, and metrics from the Anypoint Platform control plane,
integrate Flex Gateway into your Istio Service Mesh. Deploy Flex Gateway as an ingress gateway to
manage ingress north-south cluster traffic and internal east-west traffic inside the cluster.

To integrate Flex Gateway, use the following architecture diagram and tutorial. Flex Gateway is
integrated by using a modified version of the
[Istio Bookinfo sample application](https://istio.io/latest/docs/examples/bookinfo/). In the Flex
Gateway integration:

- An Istio virtual service forwards all ingress north-south traffic to Flex Gateway.

- Direct access to the `bookinfo` name space is restricted. All external traffic into the `bookinfo`
  namespace must come from the `flex` namespace. Istio automatically configures mTLS configuration
  between the `bookinfo` and `flex`.

- Flex Gateway protects and monitors the exposed product page service from ingress traffic with an
  API instance.

- The Istio sidecar intercepts east-west traffic between the product page service and the reviews
  service. Flex Gateway acts as an ingress gateway managing incoming traffic to the reviews service.

![A diagram demonstrating the architecture to integrate Flex Gateway with Istio](/mulesoft/current/en-us/gateway/1.9/_images/flex-istio-deployment.png)

> [!NOTE] In the diagram, Flex Gateway is running in Connected Mode. If Flex Gateway runs in Local
> Mode, the Anypoint Platform control plane is absent.

To configure the architecture:

1.  [Complete Before You Begin](#before-you-begin).

2.  [Set up your environment](#setup-environment).

3.  [Intercept ingress north-south traffic](#forward-ingress-traffic).

4.  [Intercept east-west traffic between services](#create-a-service).

## Before You Begin

Before you begin, install the following prerequisites:

- [Docker](https://docs.docker.com/get-started/get-docker/)

- [Download Flex Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-install#kubernetes)

- [K3d](https://k3d.io/v5.0.0/#installation) to create a Kubernetes cluster inside of docker

- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) to control the Kubernetes cluster

- [Helm](https://helm.sh/docs/intro/install/) to install Flex Gateway and Istio

## Set up Environment

1.  Create a Kubernetes cluster for this demo or skip this step if you already have a cluster you
    want to use:

    ```ssh
    k3d cluster create demo-istio --k3s-arg "--disable=traefik@server:0" --port '80:80@server:0' --port '443:443@server:0'
    ```

2.  Add the Flex Gateway and Istio Helm repositories:

    ```ssh
    helm repo add istio https://istio-release.storage.googleapis.com/charts \
    && helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm \
    && helm repo up
    ```

3.  Install Istio:

    1.  Install the Istio base chart that contains the cluster-wide Custom Resource Definitions
        (CRDs) that must be installed before deploying the Istio control plane:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-base istio/base --version 1.21.2 --set defaultRevision=default
        ```

    2.  Install the Istio discovery chart that deploys the `istiod` service:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istiod istio/istiod --version 1.21.2
        ```

    3.  Install an Istio ingress gateway:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-ingress istio/gateway --version 1.21.2
        ```

4.  Install Flex Gateway:

    1.  Create the namespace and set up the label to enable the sidecar injection:

        ```ssh
        kubectl create ns flex && kubectl label ns flex istio-injection=enabled --overwrite
        ```

    2.  Install Flex Gateway:

        ```ssh
        helm upgrade -i --wait -n flex --version 1.7.0 flex flex-gateway/flex-gateway \
        --set gateway.scope=Namespace \
        --set gateway.mode=connected \
        --set service.type=ClusterIP \
        --set service.http.port=8081 \
        --set service.https.enabled=false \
        --set-file registration.content=registration.yaml
        ```

    3.  List all services and API instances previously created:

        ```ssh
        kubectl -n flex get svc
        ```

5.  Install the `bookinfo` application:

    1.  Enable Istio label injection in the default namespace and install the `bookinfo`
        application:

        ```ssh
        kubectl create ns bookinfo \
        && kubectl label ns bookinfo istio-injection=enabled --overwrite \
        && kubectl -n bookinfo apply -l version!=v2,version!=v3 -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/bookinfo/platform/kube/bookinfo.yaml
        ```

    2.  Check the pod status:

        ```ssh
        kubectl -n bookinfo get pods
        ```

6.  Install the `sleep` application to test traffic:

    1.  Create the `test` namespace and install the `sleep` application:

        ```ssh
        kubectl create ns test \
        && kubectl label ns test istio-injection=enabled --overwrite \
        && kubectl -n test apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/sleep/sleep.yaml
        ```

    2.  Check the status of the pods:

        ```ssh
        kubectl -n test get pods
        ```

## Intercept Ingress North-South Traffic

Intercept ingress north-south traffic to protect services from external traffic.

To intercept ingress north-south traffic:

1.  Create the Flex Gateway ingress API instance to forward all ingress north-south traffic in the
    `bookinfo` namespace to the `productpage` service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: ingress
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/ingress/
        services:
          productpage:
            address: http://productpage.bookinfo.svc:9080
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with the following downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/ingress/`

        Configure the API instance with the following upstream parameters:

      - **Route label**: `productpage`

      - **Upstream URL**:
        `[http://productpage.bookinfo.svc:9080](http://productpage.bookinfo.svc:9080)`

2.  Create the `flex` Istio ingress gateway to forward the ingress traffic to Flex Gateway using a
    Istio virtual service:

    1.  Create the Flex Gateway:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: Gateway
        metadata:
          name: flex
          namespace: flex
        spec:
          selector:
            app: istio-ingress
          servers:
          - port:
              number: 80
              name: http
              protocol: HTTP
            hosts:
            - "*"
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: flex
          namespace: flex
        spec:
          hosts:
          - "*"
          gateways:
          - flex
          http:
          - route:
            - destination:
                host: flex
                port:
                  number: 8081
            rewrite:
              uri: /ingress/
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request to the `/api/v1/products/1`
        page:

        ```ssh
        curl -v http://localhost/api/v1/products/1
        ```

    3.  Ensure you receive this output:

        ```ssh
        < HTTP/1.1 200 OK
        < server: istio-envoy
        < date: Tue, 27 Feb 2024 22:06:33 GMT
        < content-type: application/json
        < content-length: 195
        < x-envoy-upstream-service-time: 8
        <
        * Connection #0 to host localhost left intact
        {"id": 2, "author": "William Shakespeare", "year": 1595, "type": "paperback", "pages": 200, "publisher": "PublisherA", "language": "English", "ISBN-10": "1234567890", "ISBN-13": "123-1234567890"}
        ```

3.  Protect the Flex Gateway API instance by applying the Basic Authentication policy:

    1.  Add the policy:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: ingress
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/ingress/
          services:
            productpage:
              address: http://productpage.bookinfo.svc:9080
          policies:
          - policyRef:
              name: http-basic-authentication-flex
            config:
              username: user1
              password: password1
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request:

        ```ssh
        curl -v http://localhost/
        ```

    3.  Make sure you receive a `401` response.

4.  Add the Message Logging policy to log traffic:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: ApiInstance
    metadata:
      name: ingress
      namespace: flex
    spec:
      address: http://0.0.0.0:8081/ingress/
      services:
        productpage:
          address: http://productpage.bookinfo.svc:9080
      policies:
      - policyRef:
          name: http-basic-authentication-flex
        config:
          username: user1
          password: password1
      - policyRef:
          name: message-logging-flex
        config:
          loggingConfiguration:
          - itemName: "Request"
            itemData:
              message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
              level: "INFO"
              firstSection: true
          - itemName: "Response"
            itemData:
              message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
              level: "INFO"
              secondSection: true
        order: 0
    EOF
    ```

## Intercept East-West Traffic Between Services

Use Flex Gateway to intercept east-west traffic between services and protect them with policies.

To intercept east-west traffic:

1.  Create the `bookinfo-reviews` API instance to forward the east-west traffic to the `reviews`
    service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: bookinfo-reviews
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/bookinfo/reviews/
        services:
          upstream:
            address: http://reviews.bookinfo.svc:9080
        policies:
        - policyRef:
            name: message-logging-flex
          config:
            loggingConfiguration:
            - itemName: "Request"
              itemData:
                message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                level: "INFO"
                firstSection: true
            - itemName: "Response"
              itemData:
                message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                level: "INFO"
                secondSection: true
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with these downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/bookinfo/reviews/`

        Configure the API instance with these upstream parameters:

      - **Route label**: `reviews`

      - **Upstream URL**: `[http://reviews.bookinfo.svc:9080](http://reviews.bookinfo.svc:9080)`

2.  Intercept the traffic between the `productpage` service and the `reviews` service and forward it
    to the `flex` service:

    1.  Create the Istio API instance:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: bookinfo-reviews
          namespace: istio-system
        spec:
          hosts:
          - reviews.bookinfo.svc.cluster.local
          http:
          - match:
            - sourceLabels:
                app: flex
            route:
            - destination:
                host: reviews.bookinfo.svc.cluster.local
                port:
                  number: 9080
          - route:
            - destination:
                host: flex.flex.svc.cluster.local
                port:
                  number: 8081
            rewrite:
              uri: /bookinfo/reviews/
        EOF
        ```

    2.  Send a test request with the `user1` username and `password1` password to the
        `/productpage`:

        ```ssh
        curl -v -u user1:password1 http://localhost/productpage
        ```

    3.  Check the Flex Gateway logs to ensure the request sent from the `productpage` service to the
        `reviews` service passed through Flex Gateway. The logs appear similar to:

        ```ssh
        [flex-gateway-envoy][info] wasm log productpage-message-logging-flex-2.flex.productpage.flex.svc main: [policy: productpage-message-logging-flex-2.flex][api: productpage.flex.svc][req: 6e1f7c32-918d-4b6a-af3f-36a4430f80ae] [accessLog] > HTTP/1.1 GET localhost/ingress/productpage
        [flex-gateway-envoy][info] wasm log bookinfo-reviews-message-logging-flex-1.flex.bookinfo-reviews.flex.svc main: [policy: bookinfo-reviews-message-logging-flex-1.flex][api: bookinfo-reviews.flex.svc][req: b23e9c64-a2aa-4464-8984-d1dd6c18f7ea] [accessLog] > HTTP/1.1 GET reviews:9080/bookinfo/reviews/reviews/0
        ```

        > [!NOTE] Use the standard output logs for a quick log check. To learn how to view standard
        > output logs, see [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.9/flex-local-view-logs).

    4.  Apply the Rate Limiting policy to the `bookinfo-reviews` API instance to protect the
        `reviews` service:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: bookinfo-reviews
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/bookinfo/reviews/
          services:
            upstream:
              address: http://reviews.bookinfo.svc:9080
          policies:
          - policyRef:
              name: message-logging-flex
            config:
              loggingConfiguration:
              - itemName: "Request"
                itemData:
                  message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                  level: "INFO"
                  firstSection: true
              - itemName: "Response"
                itemData:
                  message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                  level: "INFO"
                  secondSection: true
            order: 0
          - policyRef:
              name: rate-limiting-flex
            config:
              rateLimits:
              - timePeriodInMilliseconds: 60000
                maximumRequests: 2
              exposeHeaders: true
        EOF
        ```

3.  Restrict direct access to the `bookinfo` service:

    1.  Restrict access:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: security.istio.io/v1
        kind: AuthorizationPolicy
        metadata:
          name: flex-allow
          namespace: bookinfo
        spec:
          action: ALLOW
          rules:
          - from:
            - source:
                namespaces:
                - flex
                - bookinfo
        EOF
        ```

    2.  Send a test request from the test namespace to the `details` service:

        ```ssh
        kubectl -n test exec -ti -c sleep $(kubectl -n test get pod --no-headers -o=name) -- curl -v details.bookinfo:9080/details/0
        ```

    3.  Make sure you receive this `403 forbidden` response:

        ```ssh
        < HTTP/1.1 403 Forbidden
        < content-length: 19
        < content-type: text/plain
        < date: Thu, 09 May 2024 15:51:11 GMT
        < server: envoy
        < x-envoy-upstream-service-time: 0
        <
        * Connection #0 to host details.bookinfo left intact
        RBAC: access denied
        ```

    4.  Send this request to the `details` service to find out how to access the `bookinfo` service
        from the `flex` namespace:

        ```ssh
        kubectl -n flex exec -ti -c app  $(kubectl -n flex get pod --no-headers -o=name) -- flexctl check http http://details.bookinfo:9080/details/0
        ```

    5.  Make sure you receive this response:

        ```ssh
        [flexctl][info] Access to http address 'http://details.bookinfo:9080/details/0': ok
        ```

<!-- document id=5874d3066c2556464e57eec73e91e318b6b9489fc088db2c0fda35dda7ad5449 url=/mulesoft/current/en-us/gateway/1.13/gateway-istio.md -->

---
product: Omni Gateway
version: 1.13
---

# Integrating Omni Gateway with Istio Service Mesh

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To leverage Omni Gateway policies, logging, and metrics from the Anypoint Platform control plane,
integrate Omni Gateway into your Istio Service Mesh. Deploy Omni Gateway as an ingress gateway to
manage ingress north-south cluster traffic and internal east-west traffic inside the cluster.

To integrate Omni Gateway, use the following architecture diagram and tutorial. Omni Gateway is
integrated by using a modified version of the
[Istio Bookinfo sample application](https://istio.io/latest/docs/examples/bookinfo/). In the Omni
Gateway integration:

- An Istio virtual service forwards all ingress north-south traffic to Omni Gateway.

- Direct access to the `bookinfo` name space is restricted. All external traffic into the `bookinfo`
  namespace must come from the `flex` namespace. Istio automatically configures mTLS configuration
  between the `bookinfo` and `flex`.

- Omni Gateway protects and monitors the exposed product page service from ingress traffic with an
  API instance.

- The Istio sidecar intercepts east-west traffic between the product page service and the reviews
  service. Omni Gateway acts as an ingress gateway managing incoming traffic to the reviews service.

![A diagram demonstrating the architecture to integrate Omni Gateway with Istio](/mulesoft/current/en-us/gateway/1.13/_images/istio-deployment.png)

> [!NOTE] In the diagram, Omni Gateway is running in Connected Mode. If Omni Gateway runs in Local
> Mode, the Anypoint Platform control plane is absent.

To configure the architecture:

1.  [Complete Before You Begin](#before-you-begin).

2.  [Set up your environment](#setup-environment).

3.  [Intercept ingress north-south traffic](#forward-ingress-traffic).

4.  [Intercept east-west traffic between services](#create-a-service).

## Before You Begin

Before you begin, install the following prerequisites:

- [Docker](https://docs.docker.com/get-docker/)

- [Download Omni Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/install#kubernetes)

- [K3d](https://k3d.io/v5.0.0/#installation) to create a Kubernetes cluster inside of docker

- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) to control the Kubernetes cluster

- [Helm](https://helm.sh/docs/intro/install/) to install Omni Gateway and Istio

## Set up Environment

1.  Create a Kubernetes cluster for this demo or skip this step if you already have a cluster you
    want to use:

    ```ssh
    k3d cluster create demo-istio --k3s-arg "--disable=traefik@server:0" --port '80:80@server:0' --port '443:443@server:0'
    ```

2.  Add the Omni Gateway and Istio Helm repositories:

    ```ssh
    helm repo add istio https://istio-release.storage.googleapis.com/charts \
    && helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm \
    && helm repo up
    ```

3.  Install Istio:

    1.  Install the Istio base chart that contains the cluster-wide Custom Resource Definitions
        (CRDs) that must be installed before deploying the Istio control plane:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-base istio/base --version 1.21.2 --set defaultRevision=default
        ```

    2.  Install the Istio discovery chart that deploys the `istiod` service:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istiod istio/istiod --version 1.21.2
        ```

    3.  Install an Istio ingress gateway:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-ingress istio/gateway --version 1.21.2
        ```

4.  Install Omni Gateway:

    1.  Create the namespace and set up the label to enable the sidecar injection:

        ```ssh
        kubectl create ns flex && kubectl label ns flex istio-injection=enabled --overwrite
        ```

    2.  Install Omni Gateway:

        ```ssh
        helm upgrade -i --wait -n flex --version 1.7.0 flex flex-gateway/flex-gateway \
        --set gateway.scope=Namespace \
        --set gateway.mode=connected \
        --set service.type=ClusterIP \
        --set service.http.port=8081 \
        --set service.https.enabled=false \
        --set-file registration.content=registration.yaml
        ```

    3.  List all services and API instances previously created:

        ```ssh
        kubectl -n flex get svc
        ```

5.  Install the `bookinfo` application:

    1.  Enable Istio label injection in the default namespace and install the `bookinfo`
        application:

        ```ssh
        kubectl create ns bookinfo \
        && kubectl label ns bookinfo istio-injection=enabled --overwrite \
        && kubectl -n bookinfo apply -l version!=v2,version!=v3 -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/bookinfo/platform/kube/bookinfo.yaml
        ```

    2.  Check the pod status:

        ```ssh
        kubectl -n bookinfo get pods
        ```

6.  Install the `sleep` application to test traffic:

    1.  Create the `test` namespace and install the `sleep` application:

        ```ssh
        kubectl create ns test \
        && kubectl label ns test istio-injection=enabled --overwrite \
        && kubectl -n test apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/sleep/sleep.yaml
        ```

    2.  Check the status of the pods:

        ```ssh
        kubectl -n test get pods
        ```

## Intercept Ingress North-South Traffic

Intercept ingress north-south traffic to protect services from external traffic.

To intercept ingress north-south traffic:

1.  Create the Omni Gateway ingress API instance to forward all ingress north-south traffic in the
    `bookinfo` namespace to the `productpage` service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: ingress
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/ingress/
        services:
          productpage:
            address: http://productpage.bookinfo.svc:9080
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with the following downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/ingress/`

        Configure the API instance with the following upstream parameters:

      - **Route label**: `productpage`

      - **Upstream URL**:
        `[http://productpage.bookinfo.svc:9080](http://productpage.bookinfo.svc:9080)`

2.  Create the `flex` Istio ingress gateway to forward the ingress traffic to Omni Gateway using a
    Istio virtual service:

    1.  Create the Omni Gateway:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: Gateway
        metadata:
          name: flex
          namespace: flex
        spec:
          selector:
            app: istio-ingress
          servers:
          - port:
              number: 80
              name: http
              protocol: HTTP
            hosts:
            - "*"
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: flex
          namespace: flex
        spec:
          hosts:
          - "*"
          gateways:
          - flex
          http:
          - route:
            - destination:
                host: flex
                port:
                  number: 8081
            rewrite:
              uri: /ingress/
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request to the `/api/v1/products/1`
        page:

        ```ssh
        curl -v http://localhost/api/v1/products/1
        ```

    3.  Ensure you receive this output:

        ```ssh
        < HTTP/1.1 200 OK
        < server: istio-envoy
        < date: Tue, 27 Feb 2024 22:06:33 GMT
        < content-type: application/json
        < content-length: 195
        < x-envoy-upstream-service-time: 8
        <
        * Connection #0 to host localhost left intact
        {"id": 2, "author": "William Shakespeare", "year": 1595, "type": "paperback", "pages": 200, "publisher": "PublisherA", "language": "English", "ISBN-10": "1234567890", "ISBN-13": "123-1234567890"}
        ```

3.  Protect the Omni Gateway API instance by applying the Basic Authentication policy:

    1.  Add the policy:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: ingress
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/ingress/
          services:
            productpage:
              address: http://productpage.bookinfo.svc:9080
          policies:
          - policyRef:
              name: http-basic-authentication-flex
            config:
              username: user1
              password: password1
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request:

        ```ssh
        curl -v http://localhost/
        ```

    3.  Make sure you receive a `401` response.

4.  Add the Message Logging policy to log traffic:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: ApiInstance
    metadata:
      name: ingress
      namespace: flex
    spec:
      address: http://0.0.0.0:8081/ingress/
      services:
        productpage:
          address: http://productpage.bookinfo.svc:9080
      policies:
      - policyRef:
          name: http-basic-authentication-flex
        config:
          username: user1
          password: password1
      - policyRef:
          name: message-logging-flex
        config:
          loggingConfiguration:
          - itemName: "Request"
            itemData:
              message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
              level: "INFO"
              firstSection: true
          - itemName: "Response"
            itemData:
              message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
              level: "INFO"
              secondSection: true
        order: 0
    EOF
    ```

## Intercept East-West Traffic Between Services

Use Omni Gateway to intercept east-west traffic between services and protect them with policies.

To intercept east-west traffic:

1.  Create the `bookinfo-reviews` API instance to forward the east-west traffic to the `reviews`
    service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: bookinfo-reviews
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/bookinfo/reviews/
        services:
          upstream:
            address: http://reviews.bookinfo.svc:9080
        policies:
        - policyRef:
            name: message-logging-flex
          config:
            loggingConfiguration:
            - itemName: "Request"
              itemData:
                message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                level: "INFO"
                firstSection: true
            - itemName: "Response"
              itemData:
                message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                level: "INFO"
                secondSection: true
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with these downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/bookinfo/reviews/`

        Configure the API instance with these upstream parameters:

      - **Route label**: `reviews`

      - **Upstream URL**: `[http://reviews.bookinfo.svc:9080](http://reviews.bookinfo.svc:9080)`

2.  Intercept the traffic between the `productpage` service and the `reviews` service and forward it
    to the `flex` service:

    1.  Create the Istio API instance:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: bookinfo-reviews
          namespace: istio-system
        spec:
          hosts:
          - reviews.bookinfo.svc.cluster.local
          http:
          - match:
            - sourceLabels:
                app: flex
            route:
            - destination:
                host: reviews.bookinfo.svc.cluster.local
                port:
                  number: 9080
          - route:
            - destination:
                host: flex.flex.svc.cluster.local
                port:
                  number: 8081
            rewrite:
              uri: /bookinfo/reviews/
        EOF
        ```

    2.  Send a test request with the `user1` username and `password1` password to the
        `/productpage`:

        ```ssh
        curl -v -u user1:password1 http://localhost/productpage
        ```

    3.  Check the Omni Gateway logs to ensure the request sent from the `productpage` service to the
        `reviews` service passed through Omni Gateway. The logs appear similar to:

        ```ssh
        [flex-gateway-envoy][info] wasm log productpage-message-logging-flex-2.flex.productpage.flex.svc main: [policy: productpage-message-logging-flex-2.flex][api: productpage.flex.svc][req: 6e1f7c32-918d-4b6a-af3f-36a4430f80ae] [accessLog] > HTTP/1.1 GET localhost/ingress/productpage
        [flex-gateway-envoy][info] wasm log bookinfo-reviews-message-logging-flex-1.flex.bookinfo-reviews.flex.svc main: [policy: bookinfo-reviews-message-logging-flex-1.flex][api: bookinfo-reviews.flex.svc][req: b23e9c64-a2aa-4464-8984-d1dd6c18f7ea] [accessLog] > HTTP/1.1 GET reviews:9080/bookinfo/reviews/reviews/0
        ```

        > [!NOTE] Use the standard output logs for a quick log check. To learn how to view standard
        > output logs, see [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.13/local-view-logs).

    4.  Apply the Rate Limiting policy to the `bookinfo-reviews` API instance to protect the
        `reviews` service:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: bookinfo-reviews
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/bookinfo/reviews/
          services:
            upstream:
              address: http://reviews.bookinfo.svc:9080
          policies:
          - policyRef:
              name: message-logging-flex
            config:
              loggingConfiguration:
              - itemName: "Request"
                itemData:
                  message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                  level: "INFO"
                  firstSection: true
              - itemName: "Response"
                itemData:
                  message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                  level: "INFO"
                  secondSection: true
            order: 0
          - policyRef:
              name: rate-limiting-flex
            config:
              rateLimits:
              - timePeriodInMilliseconds: 60000
                maximumRequests: 2
              exposeHeaders: true
        EOF
        ```

3.  Restrict direct access to the `bookinfo` service:

    1.  Restrict access:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: security.istio.io/v1
        kind: AuthorizationPolicy
        metadata:
          name: flex-allow
          namespace: bookinfo
        spec:
          action: ALLOW
          rules:
          - from:
            - source:
                namespaces:
                - flex
                - bookinfo
        EOF
        ```

    2.  Send a test request from the test namespace to the `details` service:

        ```ssh
        kubectl -n test exec -ti -c sleep $(kubectl -n test get pod --no-headers -o=name) -- curl -v details.bookinfo:9080/details/0
        ```

    3.  Make sure you receive this `403 forbidden` response:

        ```ssh
        < HTTP/1.1 403 Forbidden
        < content-length: 19
        < content-type: text/plain
        < date: Thu, 09 May 2024 15:51:11 GMT
        < server: envoy
        < x-envoy-upstream-service-time: 0
        <
        * Connection #0 to host details.bookinfo left intact
        RBAC: access denied
        ```

    4.  Send this request to the `details` service to find out how to access the `bookinfo` service
        from the `flex` namespace:

        ```ssh
        kubectl -n flex exec -ti -c app  $(kubectl -n flex get pod --no-headers -o=name) -- flexctl check http http://details.bookinfo:9080/details/0
        ```

    5.  Make sure you receive this response:

        ```ssh
        [flexctl][info] Access to http address 'http://details.bookinfo:9080/details/0': ok
        ```

<!-- document id=3538e4aa78dbc0af1aea5cae079cee80bd9287e2070bb2e88296efafaea00533 url=/mulesoft/current/en-us/gateway/latest/gateway-istio.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Integrating Omni Gateway with Istio Service Mesh

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To leverage Omni Gateway policies, logging, and metrics from the Anypoint Platform control plane,
integrate Omni Gateway into your Istio Service Mesh. Deploy Omni Gateway as an ingress gateway to
manage ingress north-south cluster traffic and internal east-west traffic inside the cluster.

To integrate Omni Gateway, use the following architecture diagram and tutorial. Omni Gateway is
integrated by using a modified version of the
[Istio Bookinfo sample application](https://istio.io/latest/docs/examples/bookinfo/). In the Omni
Gateway integration:

- An Istio virtual service forwards all ingress north-south traffic to Omni Gateway.

- Direct access to the `bookinfo` name space is restricted. All external traffic into the `bookinfo`
  namespace must come from the `flex` namespace. Istio automatically configures mTLS configuration
  between the `bookinfo` and `flex`.

- Omni Gateway protects and monitors the exposed product page service from ingress traffic with an
  API instance.

- The Istio sidecar intercepts east-west traffic between the product page service and the reviews
  service. Omni Gateway acts as an ingress gateway managing incoming traffic to the reviews service.

![A diagram demonstrating the architecture to integrate Omni Gateway with Istio](/mulesoft/current/en-us/gateway/latest/_images/istio-deployment.png)

> [!NOTE] In the diagram, Omni Gateway is running in Connected Mode. If Omni Gateway runs in Local
> Mode, the Anypoint Platform control plane is absent.

To configure the architecture:

1.  [Complete Before You Begin](#before-you-begin).

2.  [Set up your environment](#setup-environment).

3.  [Intercept ingress north-south traffic](#forward-ingress-traffic).

4.  [Intercept east-west traffic between services](#create-a-service).

## Before You Begin

Before you begin, install the following prerequisites:

- [Docker](https://docs.docker.com/get-docker/)

- [Download Omni Gateway for Use in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/install#kubernetes)

- [K3d](https://k3d.io/v5.0.0/#installation) to create a Kubernetes cluster inside of docker

- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) to control the Kubernetes cluster

- [Helm](https://helm.sh/docs/intro/install/) to install Omni Gateway and Istio

## Set up Environment

1.  Create a Kubernetes cluster for this demo or skip this step if you already have a cluster you
    want to use:

    ```ssh
    k3d cluster create demo-istio --k3s-arg "--disable=traefik@server:0" --port '80:80@server:0' --port '443:443@server:0'
    ```

2.  Add the Omni Gateway and Istio Helm repositories:

    ```ssh
    helm repo add istio https://istio-release.storage.googleapis.com/charts \
    && helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm \
    && helm repo up
    ```

3.  Install Istio:

    1.  Install the Istio base chart that contains the cluster-wide Custom Resource Definitions
        (CRDs) that must be installed before deploying the Istio control plane:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-base istio/base --version 1.21.2 --set defaultRevision=default
        ```

    2.  Install the Istio discovery chart that deploys the `istiod` service:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istiod istio/istiod --version 1.21.2
        ```

    3.  Install an Istio ingress gateway:

        ```ssh
        helm upgrade -i --wait --create-namespace -n istio-system istio-ingress istio/gateway --version 1.21.2
        ```

4.  Install Omni Gateway:

    1.  Create the namespace and set up the label to enable the sidecar injection:

        ```ssh
        kubectl create ns flex && kubectl label ns flex istio-injection=enabled --overwrite
        ```

    2.  Install Omni Gateway:

        ```ssh
        helm upgrade -i --wait -n flex --version 1.7.0 flex flex-gateway/flex-gateway \
        --set gateway.scope=Namespace \
        --set gateway.mode=connected \
        --set service.type=ClusterIP \
        --set service.http.port=8081 \
        --set service.https.enabled=false \
        --set-file registration.content=registration.yaml
        ```

    3.  List all services and API instances previously created:

        ```ssh
        kubectl -n flex get svc
        ```

5.  Install the `bookinfo` application:

    1.  Enable Istio label injection in the default namespace and install the `bookinfo`
        application:

        ```ssh
        kubectl create ns bookinfo \
        && kubectl label ns bookinfo istio-injection=enabled --overwrite \
        && kubectl -n bookinfo apply -l version!=v2,version!=v3 -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/bookinfo/platform/kube/bookinfo.yaml
        ```

    2.  Check the pod status:

        ```ssh
        kubectl -n bookinfo get pods
        ```

6.  Install the `sleep` application to test traffic:

    1.  Create the `test` namespace and install the `sleep` application:

        ```ssh
        kubectl create ns test \
        && kubectl label ns test istio-injection=enabled --overwrite \
        && kubectl -n test apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/sleep/sleep.yaml
        ```

    2.  Check the status of the pods:

        ```ssh
        kubectl -n test get pods
        ```

## Intercept Ingress North-South Traffic

Intercept ingress north-south traffic to protect services from external traffic.

To intercept ingress north-south traffic:

1.  Create the Omni Gateway ingress API instance to forward all ingress north-south traffic in the
    `bookinfo` namespace to the `productpage` service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: ingress
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/ingress/
        services:
          productpage:
            address: http://productpage.bookinfo.svc:9080
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with the following downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/ingress/`

        Configure the API instance with the following upstream parameters:

      - **Route label**: `productpage`

      - **Upstream URL**:
        `[http://productpage.bookinfo.svc:9080](http://productpage.bookinfo.svc:9080)`

2.  Create the `flex` Istio ingress gateway to forward the ingress traffic to Omni Gateway using a
    Istio virtual service:

    1.  Create the Omni Gateway:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: Gateway
        metadata:
          name: flex
          namespace: flex
        spec:
          selector:
            app: istio-ingress
          servers:
          - port:
              number: 80
              name: http
              protocol: HTTP
            hosts:
            - "*"
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: flex
          namespace: flex
        spec:
          hosts:
          - "*"
          gateways:
          - flex
          http:
          - route:
            - destination:
                host: flex
                port:
                  number: 8081
            rewrite:
              uri: /ingress/
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request to the `/api/v1/products/1`
        page:

        ```ssh
        curl -v http://localhost/api/v1/products/1
        ```

    3.  Ensure you receive this output:

        ```ssh
        < HTTP/1.1 200 OK
        < server: istio-envoy
        < date: Tue, 27 Feb 2024 22:06:33 GMT
        < content-type: application/json
        < content-length: 195
        < x-envoy-upstream-service-time: 8
        <
        * Connection #0 to host localhost left intact
        {"id": 2, "author": "William Shakespeare", "year": 1595, "type": "paperback", "pages": 200, "publisher": "PublisherA", "language": "English", "ISBN-10": "1234567890", "ISBN-13": "123-1234567890"}
        ```

3.  Protect the Omni Gateway API instance by applying the Basic Authentication policy:

    1.  Add the policy:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: ingress
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/ingress/
          services:
            productpage:
              address: http://productpage.bookinfo.svc:9080
          policies:
          - policyRef:
              name: http-basic-authentication-flex
            config:
              username: user1
              password: password1
        EOF
        ```

    2.  Wait a few seconds (approximately 10) and send a test request:

        ```ssh
        curl -v http://localhost/
        ```

    3.  Make sure you receive a `401` response.

4.  Add the Message Logging policy to log traffic:

    ```ssh
    cat <<EOF | kubectl apply -f -
    ---
    apiVersion: gateway.mulesoft.com/v1alpha1
    kind: ApiInstance
    metadata:
      name: ingress
      namespace: flex
    spec:
      address: http://0.0.0.0:8081/ingress/
      services:
        productpage:
          address: http://productpage.bookinfo.svc:9080
      policies:
      - policyRef:
          name: http-basic-authentication-flex
        config:
          username: user1
          password: password1
      - policyRef:
          name: message-logging-flex
        config:
          loggingConfiguration:
          - itemName: "Request"
            itemData:
              message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
              level: "INFO"
              firstSection: true
          - itemName: "Response"
            itemData:
              message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
              level: "INFO"
              secondSection: true
        order: 0
    EOF
    ```

## Intercept East-West Traffic Between Services

Use Omni Gateway to intercept east-west traffic between services and protect them with policies.

To intercept east-west traffic:

1.  Create the `bookinfo-reviews` API instance to forward the east-west traffic to the `reviews`
    service:

    - Local Mode:

      ```ssh
      cat <<EOF | kubectl apply -f -
      ---
      apiVersion: gateway.mulesoft.com/v1alpha1
      kind: ApiInstance
      metadata:
        name: bookinfo-reviews
        namespace: flex
      spec:
        address: http://0.0.0.0:8081/bookinfo/reviews/
        services:
          upstream:
            address: http://reviews.bookinfo.svc:9080
        policies:
        - policyRef:
            name: message-logging-flex
          config:
            loggingConfiguration:
            - itemName: "Request"
              itemData:
                message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                level: "INFO"
                firstSection: true
            - itemName: "Response"
              itemData:
                message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                level: "INFO"
                secondSection: true
      EOF
      ```

    - Connected Mode:

      To add an API instance in Connected Mode, see
      [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex).

      Configure the API instance with these downstream parameters:

      - **Protocol**: **HTTP**

      - **Port**: `8081`

      - **Base Path**: `/bookinfo/reviews/`

        Configure the API instance with these upstream parameters:

      - **Route label**: `reviews`

      - **Upstream URL**: `[http://reviews.bookinfo.svc:9080](http://reviews.bookinfo.svc:9080)`

2.  Intercept the traffic between the `productpage` service and the `reviews` service and forward it
    to the `flex` service:

    1.  Create the Istio API instance:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: networking.istio.io/v1alpha3
        kind: VirtualService
        metadata:
          name: bookinfo-reviews
          namespace: istio-system
        spec:
          hosts:
          - reviews.bookinfo.svc.cluster.local
          http:
          - match:
            - sourceLabels:
                app: flex
            route:
            - destination:
                host: reviews.bookinfo.svc.cluster.local
                port:
                  number: 9080
          - route:
            - destination:
                host: flex.flex.svc.cluster.local
                port:
                  number: 8081
            rewrite:
              uri: /bookinfo/reviews/
        EOF
        ```

    2.  Send a test request with the `user1` username and `password1` password to the
        `/productpage`:

        ```ssh
        curl -v -u user1:password1 http://localhost/productpage
        ```

    3.  Check the Omni Gateway logs to ensure the request sent from the `productpage` service to the
        `reviews` service passed through Omni Gateway. The logs appear similar to:

        ```ssh
        [flex-gateway-envoy][info] wasm log productpage-message-logging-flex-2.flex.productpage.flex.svc main: [policy: productpage-message-logging-flex-2.flex][api: productpage.flex.svc][req: 6e1f7c32-918d-4b6a-af3f-36a4430f80ae] [accessLog] > HTTP/1.1 GET localhost/ingress/productpage
        [flex-gateway-envoy][info] wasm log bookinfo-reviews-message-logging-flex-1.flex.bookinfo-reviews.flex.svc main: [policy: bookinfo-reviews-message-logging-flex-1.flex][api: bookinfo-reviews.flex.svc][req: b23e9c64-a2aa-4464-8984-d1dd6c18f7ea] [accessLog] > HTTP/1.1 GET reviews:9080/bookinfo/reviews/reviews/0
        ```

        > [!NOTE] Use the standard output logs for a quick log check. To learn how to view standard
        > output logs, see [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs).

    4.  Apply the Rate Limiting policy to the `bookinfo-reviews` API instance to protect the
        `reviews` service:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: gateway.mulesoft.com/v1alpha1
        kind: ApiInstance
        metadata:
          name: bookinfo-reviews
          namespace: flex
        spec:
          address: http://0.0.0.0:8081/bookinfo/reviews/
          services:
            upstream:
              address: http://reviews.bookinfo.svc:9080
          policies:
          - policyRef:
              name: message-logging-flex
            config:
              loggingConfiguration:
              - itemName: "Request"
                itemData:
                  message: "#['> ' ++ attributes.version ++ ' ' ++  attributes.method ++ ' ' ++ attributes.headers.host ++ attributes.requestUri]"
                  level: "INFO"
                  firstSection: true
              - itemName: "Response"
                itemData:
                  message: "#['< Status=' ++ attributes.statusCode ++ ' Length=' ++ (attributes.headers['content-length'] default 'none') ++ ' Time=' ++ (attributes.headers['x-envoy-upstream-service-time'] default 'none')]"
                  level: "INFO"
                  secondSection: true
            order: 0
          - policyRef:
              name: rate-limiting-flex
            config:
              rateLimits:
              - timePeriodInMilliseconds: 60000
                maximumRequests: 2
              exposeHeaders: true
        EOF
        ```

3.  Restrict direct access to the `bookinfo` service:

    1.  Restrict access:

        ```ssh
        cat <<EOF | kubectl apply -f -
        ---
        apiVersion: security.istio.io/v1
        kind: AuthorizationPolicy
        metadata:
          name: flex-allow
          namespace: bookinfo
        spec:
          action: ALLOW
          rules:
          - from:
            - source:
                namespaces:
                - flex
                - bookinfo
        EOF
        ```

    2.  Send a test request from the test namespace to the `details` service:

        ```ssh
        kubectl -n test exec -ti -c sleep $(kubectl -n test get pod --no-headers -o=name) -- curl -v details.bookinfo:9080/details/0
        ```

    3.  Make sure you receive this `403 forbidden` response:

        ```ssh
        < HTTP/1.1 403 Forbidden
        < content-length: 19
        < content-type: text/plain
        < date: Thu, 09 May 2024 15:51:11 GMT
        < server: envoy
        < x-envoy-upstream-service-time: 0
        <
        * Connection #0 to host details.bookinfo left intact
        RBAC: access denied
        ```

    4.  Send this request to the `details` service to find out how to access the `bookinfo` service
        from the `flex` namespace:

        ```ssh
        kubectl -n flex exec -ti -c app  $(kubectl -n flex get pod --no-headers -o=name) -- flexctl check http http://details.bookinfo:9080/details/0
        ```

    5.  Make sure you receive this response:

        ```ssh
        [flexctl][info] Access to http address 'http://details.bookinfo:9080/details/0': ok
        ```

<!-- document id=2ade8e45f193cbd03d6f87a69ac8178ad06d92dd5f5b6bdcbf6377adce88d4d5 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-uc-overview.md -->

---
product: Omni Gateway
version: 1.12
---

# Integration Use Cases

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following integration use cases are determined by the ownership of the API provider and API
consumer. Each use case shows physical patterns that demonstrate the necessary services in the
system.

For the following use case diagrams, Flex Gateway is running in Connected Mode. However, you can
also run Flex Gateway in Local Mode or use a combination of Connected Mode and Local Mode for
separate runtimes in the same or in different environments.

The use case diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

Flex Gateway supports four use cases:

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4)

![The four use cases are linked to products that they can support.](/mulesoft/current/en-us/gateway/1.12/_images/ad-intergration-use-cases.png)

Each use case supports different integration patterns that vary depending on the location of APIs
relative to the network in which Flex Gateway is located. You can use different use case patterns,
depending on the different API owners and networks in your system.

In each use case, there are three different classifications of networks. The classifications
describe the relation of each network to your organization and the network that Flex Gateway is in:

- Organization internal

  Networks owned by your organization and in the same network as Flex Gateway

- Organization external

  Trusted networks external to your organization but in a different network than Flex Gateway, for
  example, your organization’s Splunk instance

- Non-Organization external

  External networks untrusted by your company and in a different network as Flex Gateway. An API
  provider’s or API consumers network status affects the necessary security protocols (mTLS) you
  take when communicating between networks

If an API provider or API consumer is organization-owned, it belongs to either the organization’s
internal network or its external networks.

The following tables:

- Relate the previously mentioned use cases to use case patterns

- Show the networks involved in the pattern

- Indicate whether Flex Gateway acts as an ingress, egress, or both

## Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1#pattern-1a">Pattern 1A: Organization internal API exposed to an organization internal consumer that uses the same VPC or network as the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1#pattern-1b">Pattern 1B: Organization internal API exposed to an organization internal consumer that uses a different VPC or network from the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1#pattern-2">Pattern 2: Organization internal API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1#pattern-3">Pattern 3: Organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1#pattern-4">Pattern 4: Organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2#pattern-5">Pattern 5: Organization internal API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2#pattern-6">Pattern 6: Organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3#pattern-7">Pattern 7: Non-organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3#pattern-8">Pattern 8: Non-organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 4: Non-Organization-Owned API Exposed to an External Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4#pattern-9">Pattern 9: Non-organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## mTLS considerations for integration flows

Flex Gateway supports Mutual Transport Layer Security (mTLS) for all Flex Gateway-initiated and Flex
Gateway-terminated connections. Mulesoft recommends using mTLS on all communication flows.

For inbound connections that cross a network security boundary, use a network application firewall
as close to the boundary as possible. For inbound connections, configure the external mTLS
connection to terminate at the firewall and configure a new mTLS context between the firewall and
Flex Gateway.

### Certificate authorities

Different certificate authorities (CA) participate in the mTLS connection, depending on the type of
integration. In the use case diagrams, color codes and labels represent the different mTLS contexts.
Each mTLS context contains a truststore that contains CAs for validating far-side certificates and a
keystore that contains a certificate issued by this same CA. The following table describes the three
possible mTLS contexts:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>mTLS context symbol</th><th>Certificate authority</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.12/_images/ad-internal-org-mtls.png" alt="Organization internal mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization internal mTLS</p></div></div></td><td><div><div><p>For internal network communication, the expectation is that only the customer organization uses these certificates within the internal network.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.12/_images/ad-external-org-mtls.png" alt="Organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization external mTLS</p></div></div></td><td><div><div><p>For external communication with trusted parties over the public internet, the organization can issue certificates that external consumers or third parties can use to access the services provided by the organization.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.12/_images/ad-external-non-org-mtls.png" alt="Non-organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Non-organization external mTLS</p></div></div></td><td><div><div><p>For external communication with entities that aren’t trusted, the third party organization controls the CA. The third party CA issues certificates for the organization to use when communicating with third-party services.</p></div></div></td></tr></tbody></table>

## See Also

- [Flex Gateway Deployment Models](https://docs.mulesoft.com/gateway/1.12/flex-architecture-basic-deployments)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.12/flex-architecture-shared-storage)

<!-- document id=fcf5468f3d19ecef0361448d4fde1117021031e951cbdc54b45b32e214ad18c9 url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-uc-overview.md -->

---
product: Omni Gateway
version: 1.13
---

# Integration Use Cases

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following integration use cases are determined by the ownership of the API provider and API
consumer. Each use case shows physical patterns that demonstrate the necessary services in the
system.

For the following use case diagrams, Omni Gateway is running in Connected Mode. However, you can
also run Omni Gateway in Local Mode or use a combination of Connected Mode and Local Mode for
separate runtimes in the same or in different environments.

The use case diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

Omni Gateway supports four use cases:

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4)

![The four use cases are linked to products that they can support.](/mulesoft/current/en-us/gateway/1.13/_images/ad-intergration-use-cases.png)

Each use case supports different integration patterns that vary depending on the location of APIs
relative to the network in which Omni Gateway is located. You can use different use case patterns,
depending on the different API owners and networks in your system.

In each use case, there are three different classifications of networks. The classifications
describe the relation of each network to your organization and the network that Omni Gateway is in:

- Organization internal

  Networks owned by your organization and in the same network as Omni Gateway

- Organization external

  Trusted networks external to your organization but in a different network than Omni Gateway, for
  example, your organization’s Splunk instance

- Non-Organization external

  External networks untrusted by your company and in a different network as Omni Gateway. An API
  provider’s or API consumers network status affects the necessary security protocols (mTLS) you
  take when communicating between networks

If an API provider or API consumer is organization-owned, it belongs to either the organization’s
internal network or its external networks.

The following tables:

- Relate the previously mentioned use cases to use case patterns

- Show the networks involved in the pattern

- Indicate whether Omni Gateway acts as an ingress, egress, or both

## Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1#pattern-1a">Pattern 1A: Organization internal API exposed to an organization internal consumer that uses the same VPC or network as the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1#pattern-1b">Pattern 1B: Organization internal API exposed to an organization internal consumer that uses a different VPC or network from the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1#pattern-2">Pattern 2: Organization internal API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1#pattern-3">Pattern 3: Organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1#pattern-4">Pattern 4: Organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2#pattern-5">Pattern 5: Organization internal API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2#pattern-6">Pattern 6: Organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3#pattern-7">Pattern 7: Non-organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3#pattern-8">Pattern 8: Non-organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 4: Non-Organization-Owned API Exposed to an External Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4#pattern-9">Pattern 9: Non-organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## mTLS considerations for integration flows

Omni Gateway supports Mutual Transport Layer Security (mTLS) for all Omni Gateway-initiated and Omni
Gateway-terminated connections. Mulesoft recommends using mTLS on all communication flows.

For inbound connections that cross a network security boundary, use a network application firewall
as close to the boundary as possible. For inbound connections, configure the external mTLS
connection to terminate at the firewall and configure a new mTLS context between the firewall and
Omni Gateway.

### Certificate authorities

Different certificate authorities (CA) participate in the mTLS connection, depending on the type of
integration. In the use case diagrams, color codes and labels represent the different mTLS contexts.
Each mTLS context contains a truststore that contains CAs for validating far-side certificates and a
keystore that contains a certificate issued by this same CA. The following table describes the three
possible mTLS contexts:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>mTLS context symbol</th><th>Certificate authority</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.13/_images/ad-internal-org-mtls.png" alt="Organization internal mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization internal mTLS</p></div></div></td><td><div><div><p>For internal network communication, the expectation is that only the customer organization uses these certificates within the internal network.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.13/_images/ad-external-org-mtls.png" alt="Organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization external mTLS</p></div></div></td><td><div><div><p>For external communication with trusted parties over the public internet, the organization can issue certificates that external consumers or third parties can use to access the services provided by the organization.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.13/_images/ad-external-non-org-mtls.png" alt="Non-organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Non-organization external mTLS</p></div></div></td><td><div><div><p>For external communication with entities that aren’t trusted, the third party organization controls the CA. The third party CA issues certificates for the organization to use when communicating with third-party services.</p></div></div></td></tr></tbody></table>

## See Also

- [Omni Gateway Deployment Models](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-basic-deployments)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-shared-storage)

<!-- document id=cd890289a927812530ca042fd8ba655c660d99d4d08f0084247b134eaef5f2ee url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-uc-overview.md -->

---
product: Omni Gateway
version: 1.9
---

# Integration Use Cases

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following integration use cases are determined by the ownership of the API provider and API
consumer. Each use case shows physical patterns that demonstrate the necessary services in the
system.

For the following use case diagrams, Flex Gateway is running in Connected Mode. However, you can
also run Flex Gateway in Local Mode or use a combination of Connected Mode and Local Mode for
separate runtimes in the same or in different environments.

The use case diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

Flex Gateway supports four use cases:

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4)

![The four use cases are linked to products that they can support.](/mulesoft/current/en-us/gateway/1.9/_images/ad-intergration-use-cases.png)

Each use case supports different integration patterns that vary depending on the location of APIs
relative to the network in which Flex Gateway is located. You can use different use case patterns,
depending on the different API owners and networks in your system.

In each use case, there are three different classifications of networks. The classifications
describe the relation of each network to your organization and the network that Flex Gateway is in:

- Organization internal

  Networks owned by your organization and in the same network as Flex Gateway

- Organization external

  Trusted networks external to your organization but in a different network than Flex Gateway, for
  example, your organization’s Splunk instance

- Non-Organization external

  External networks untrusted by your company and in a different network as Flex Gateway. An API
  provider’s or API consumers network status affects the necessary security protocols (mTLS) you
  take when communicating between networks

If an API provider or API consumer is organization-owned, it belongs to either the organization’s
internal network or its external networks.

The following tables:

- Relate the previously mentioned use cases to use case patterns

- Show the networks involved in the pattern

- Indicate whether Flex Gateway acts as an ingress, egress, or both

## Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1#pattern-1a">Pattern 1A: Organization internal API exposed to an organization internal consumer that uses the same VPC or network as the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1#pattern-1b">Pattern 1B: Organization internal API exposed to an organization internal consumer that uses a different VPC or network from the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1#pattern-2">Pattern 2: Organization internal API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1#pattern-3">Pattern 3: Organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1#pattern-4">Pattern 4: Organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2#pattern-5">Pattern 5: Organization internal API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2#pattern-6">Pattern 6: Organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3#pattern-7">Pattern 7: Non-organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3#pattern-8">Pattern 8: Non-organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 4: Non-Organization-Owned API Exposed to an External Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Flex Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4#pattern-9">Pattern 9: Non-organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## mTLS considerations for integration flows

Flex Gateway supports Mutual Transport Layer Security (mTLS) for all Flex Gateway-initiated and Flex
Gateway-terminated connections. Mulesoft recommends using mTLS on all communication flows.

For inbound connections that cross a network security boundary, use a network application firewall
as close to the boundary as possible. For inbound connections, configure the external mTLS
connection to terminate at the firewall and configure a new mTLS context between the firewall and
Flex Gateway.

### Certificate authorities

Different certificate authorities (CA) participate in the mTLS connection, depending on the type of
integration. In the use case diagrams, color codes and labels represent the different mTLS contexts.
Each mTLS context contains a truststore that contains CAs for validating far-side certificates and a
keystore that contains a certificate issued by this same CA. The following table describes the three
possible mTLS contexts:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>mTLS context symbol</th><th>Certificate authority</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.9/_images/ad-internal-org-mtls.png" alt="Organization internal mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization internal mTLS</p></div></div></td><td><div><div><p>For internal network communication, the expectation is that only the customer organization uses these certificates within the internal network.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.9/_images/ad-external-org-mtls.png" alt="Organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization external mTLS</p></div></div></td><td><div><div><p>For external communication with trusted parties over the public internet, the organization can issue certificates that external consumers or third parties can use to access the services provided by the organization.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/1.9/_images/ad-external-non-org-mtls.png" alt="Non-organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Non-organization external mTLS</p></div></div></td><td><div><div><p>For external communication with entities that aren’t trusted, the third party organization controls the CA. The third party CA issues certificates for the organization to use when communicating with third-party services.</p></div></div></td></tr></tbody></table>

## See Also

- [Flex Gateway Deployment Models](https://docs.mulesoft.com/gateway/1.9/flex-architecture-basic-deployments)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.9/flex-architecture-shared-storage)

<!-- document id=b97ef670e2793c1b77f9491deacbe668417507973bea1a2bf9d2dfc04531879a url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-uc-overview.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Integration Use Cases

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following integration use cases are determined by the ownership of the API provider and API
consumer. Each use case shows physical patterns that demonstrate the necessary services in the
system.

For the following use case diagrams, Omni Gateway is running in Connected Mode. However, you can
also run Omni Gateway in Local Mode or use a combination of Connected Mode and Local Mode for
separate runtimes in the same or in different environments.

The use case diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

Omni Gateway supports four use cases:

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4)

![The four use cases are linked to products that they can support.](/mulesoft/current/en-us/gateway/latest/_images/ad-intergration-use-cases.png)

Each use case supports different integration patterns that vary depending on the location of APIs
relative to the network in which Omni Gateway is located. You can use different use case patterns,
depending on the different API owners and networks in your system.

In each use case, there are three different classifications of networks. The classifications
describe the relation of each network to your organization and the network that Omni Gateway is in:

- Organization internal

  Networks owned by your organization and in the same network as Omni Gateway

- Organization external

  Trusted networks external to your organization but in a different network than Omni Gateway, for
  example, your organization’s Splunk instance

- Non-Organization external

  External networks untrusted by your company and in a different network as Omni Gateway. An API
  provider’s or API consumers network status affects the necessary security protocols (mTLS) you
  take when communicating between networks

If an API provider or API consumer is organization-owned, it belongs to either the organization’s
internal network or its external networks.

The following tables:

- Relate the previously mentioned use cases to use case patterns

- Show the networks involved in the pattern

- Indicate whether Omni Gateway acts as an ingress, egress, or both

## Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1#pattern-1a">Pattern 1A: Organization internal API exposed to an organization internal consumer that uses the same VPC or network as the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1#pattern-1b">Pattern 1B: Organization internal API exposed to an organization internal consumer that uses a different VPC or network from the API</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1#pattern-2">Pattern 2: Organization internal API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1#pattern-3">Pattern 3: Organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1#pattern-4">Pattern 4: Organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2#pattern-5">Pattern 5: Organization internal API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2#pattern-6">Pattern 6: Organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3#pattern-7">Pattern 7: Non-organization external API exposed to an organization internal consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization internal</p></div></div></td><td><div><div><p>Egress</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3#pattern-8">Pattern 8: Non-organization external API exposed to an organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## Use Case 4: Non-Organization-Owned API Exposed to an External Non-Organization-Owned API Consumer

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Provider Network</th><th>Consumer Network</th><th>Role of Omni Gateway</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4#pattern-9">Pattern 9: Non-organization external API exposed to a non-organization external consumer</a></p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Non-organization external</p></div></div></td><td><div><div><p>Ingress and egress</p></div></div></td></tr></tbody></table>

## mTLS considerations for integration flows

Omni Gateway supports Mutual Transport Layer Security (mTLS) for all Omni Gateway-initiated and Omni
Gateway-terminated connections. Mulesoft recommends using mTLS on all communication flows.

For inbound connections that cross a network security boundary, use a network application firewall
as close to the boundary as possible. For inbound connections, configure the external mTLS
connection to terminate at the firewall and configure a new mTLS context between the firewall and
Omni Gateway.

### Certificate authorities

Different certificate authorities (CA) participate in the mTLS connection, depending on the type of
integration. In the use case diagrams, color codes and labels represent the different mTLS contexts.
Each mTLS context contains a truststore that contains CAs for validating far-side certificates and a
keystore that contains a certificate issued by this same CA. The following table describes the three
possible mTLS contexts:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>mTLS context symbol</th><th>Certificate authority</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/latest/_images/ad-internal-org-mtls.png" alt="Organization internal mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization internal mTLS</p></div></div></td><td><div><div><p>For internal network communication, the expectation is that only the customer organization uses these certificates within the internal network.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/latest/_images/ad-external-org-mtls.png" alt="Organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Organization external mTLS</p></div></div></td><td><div><div><p>For external communication with trusted parties over the public internet, the organization can issue certificates that external consumers or third parties can use to access the services provided by the organization.</p></div></div></td></tr><tr><td><div><div><p><span><img src="https://docs.mulesoft.com/gateway/latest/_images/ad-external-non-org-mtls.png" alt="Non-organization external mTLS symbol"></span></p></div></div></td><td><div><div><p>Non-organization external mTLS</p></div></div></td><td><div><div><p>For external communication with entities that aren’t trusted, the third party organization controls the CA. The third party CA issues certificates for the organization to use when communicating with third-party services.</p></div></div></td></tr></tbody></table>

## See Also

- [Omni Gateway Deployment Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-basic-deployments)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-shared-storage)

<!-- document id=f6637daf40db59ffa75ff0589d4db6465223b9d2433409efa408d5f9bfd4c43f url=/mulesoft/current/en-us/gateway/1.12/policies-included-ip-allowlist.md -->

---
product: Omni Gateway
version: 1.12
keywords: ip, allowlist, validation, api gateway, flex gateway, gateway, policy
---

# IP Allowlist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Allowlist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows a list or range of specified IP addresses to request access</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Allowlist policy allows a list or a range of specified IP addresses access to a protected
resource when a match is found between a source IP (specified when configuring the policy) and a
list of individual IPs or range of IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP used by the policy to determine whether the IP
belongs to the policy’s restricted IP list.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ip-allowlist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-allowlist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Allowlist</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Allowlist in Your Policy

Specify IP addresses to allow access to your policy based on:

- The IP address of the request

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header

- Any other origin.

### Allowlisting Access Based on the IP address of the Request

Allowlist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the Allowlist field, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30`, which
  includes the consolidated range `192.168.3.01` through `192.168.3.3`.

- Define a whole range of IP addresses by stating the relevant octets of the IP address you want to
  permit, for example, setting `192.168`, which includes IP addresses from `192.168.0.0` through
  `192.168.255.255`.

### Allowlisting Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can allowlist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request.

For example, if you want to allowlist `192.168.2.3`(private IP) and the address of a client
connecting through an HTTP proxy is `92.40.1.255` (public IP), the client requests appear with the
public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=8a7a50edeb4766bcbfe1ad9e660bb677a6801d219a720bdc5f572542280a3ba0 url=/mulesoft/current/en-us/gateway/1.13/policies-included-ip-allowlist.md -->

---
product: Omni Gateway
version: 1.13
keywords: ip, allowlist, validation, api gateway, flex gateway, gateway, policy
---

# IP Allowlist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Allowlist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows a list or range of specified IP addresses to request access</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-allowlist-release-notes">IP Allowlist</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Allowlist policy allows a list or a range of specified IP addresses access to a protected
resource when a match is found between a source IP (specified when configuring the policy) and a
list of individual IPs or range of IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP used by the policy to determine whether the IP
belongs to the policy’s restricted IP list.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ip-allowlist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-allowlist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Allowlist</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Allowlist in Your Policy

Specify IP addresses to allow access to your policy based on:

- The IP address of the request

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header

- Any other origin.

### Allowlisting Access Based on the IP address of the Request

Allowlist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the Allowlist field, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30`, which
  includes the consolidated range `192.168.3.01` through `192.168.3.3`.

- Define a whole range of IP addresses by stating the relevant octets of the IP address you want to
  permit, for example, setting `192.168`, which includes IP addresses from `192.168.0.0` through
  `192.168.255.255`.

### Allowlisting Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can allowlist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request.

For example, if you want to allowlist `192.168.2.3`(private IP) and the address of a client
connecting through an HTTP proxy is `92.40.1.255` (public IP), the client requests appear with the
public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=776a6c4bdfd5bc85efebe7df81c18985f560a458669cea747c5d08d7518717ae url=/mulesoft/current/en-us/gateway/1.9/policies-included-ip-allowlist.md -->

---
product: Omni Gateway
version: 1.9
keywords: ip, allowlist, validation, api gateway, flex gateway, gateway, policy
---

# IP Allowlist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Allowlist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows a list or range of specified IP addresses to request access</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Allowlist policy allows a list or a range of specified IP addresses access to a protected
resource when a match is found between a source IP (specified when configuring the policy) and a
list of individual IPs or range of IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP used by the policy to determine whether the IP
belongs to the policy’s restricted IP list.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: ip-allowlist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-allowlist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Allowlist</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Allowlist in Your Policy

Specify IP addresses to allow access to your policy based on:

- The IP address of the request

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header

- Any other origin.

### Allowlisting Access Based on the IP address of the Request

Allowlist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the Allowlist field, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30`, which
  includes the consolidated range `192.168.3.01` through `192.168.3.3`.

- Define a whole range of IP addresses by stating the relevant octets of the IP address you want to
  permit, for example, setting `192.168`, which includes IP addresses from `192.168.0.0` through
  `192.168.255.255`.

### Allowlisting Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can allowlist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request.

For example, if you want to allowlist `192.168.2.3`(private IP) and the address of a client
connecting through an HTTP proxy is `92.40.1.255` (public IP), the client requests appear with the
public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=eaca38a13f0e3d73ec85835806d8c1480a8575201f8ef8700eea05365497c710 url=/mulesoft/current/en-us/gateway/latest/policies-included-ip-allowlist.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: ip, allowlist, validation, api gateway, flex gateway, gateway, policy
---

# IP Allowlist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Allowlist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows a list or range of specified IP addresses to request access</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-allowlist-release-notes">IP Allowlist</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Allowlist policy allows a list or a range of specified IP addresses access to a protected
resource when a match is found between a source IP (specified when configuring the policy) and a
list of individual IPs or range of IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP used by the policy to determine whether the IP
belongs to the policy’s restricted IP list.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ip-allowlist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-allowlist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Allowlist</p></div></div></td><td><div><div><p>The list of IP addresses allowed access to the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Allowlist in Your Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Allowlist in Your Policy

Specify IP addresses to allow access to your policy based on:

- The IP address of the request

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header

- Any other origin.

### Allowlisting Access Based on the IP address of the Request

Allowlist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the Allowlist field, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30`, which
  includes the consolidated range `192.168.3.01` through `192.168.3.3`.

- Define a whole range of IP addresses by stating the relevant octets of the IP address you want to
  permit, for example, setting `192.168`, which includes IP addresses from `192.168.0.0` through
  `192.168.255.255`.

### Allowlisting Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can allowlist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request.

For example, if you want to allowlist `192.168.2.3`(private IP) and the address of a client
connecting through an HTTP proxy is `92.40.1.255` (public IP), the client requests appear with the
public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=92fabfa8993285a82e098a526f5ad5eb1c9a11124b65182b783701286b6ff815 url=/mulesoft/current/en-us/gateway/1.12/policies-included-ip-blocklist.md -->

---
product: Omni Gateway
version: 1.12
keywords: ip, blocklist, validation, api gateway, flex gateway, gateway, policy
---

# IP Blocklist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Blocklist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Blocklist policy controls access to a configured API endpoint from either a single IP address
or a range of IP addresses.

The IP Blocklist policy restricts access to a protected resource when a match is found between a
source IP (specified when configuring the policy) and either a list of individual IPs or a range of
IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP to be used when the policy tries to determine whether
the IP belongs to the restricted IP list defined in the policy.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ip-blocklist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-blocklist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Blocklist</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Blocklist in the Policy

Specify IP addresses to block in your policy based on:

- The IP address of the request.

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header.

- Any other origin.

### Blocklist Access Based on the IP Address of the Request

Blocklist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the white space, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30` includes
  the consolidated range `192.168.3.0` through `192.168.3.3`.

- Define a whole range of IP addresses by specifying the relevant octets of the IP address that you
  want to permit, for example, setting `192.168` will include IP addresses from `192.168.0.0`
  through `192.168.255.255`.

### Blocklist Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can blocklist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request

For example, if you want to blocklist `192.168.2.3` and the address of a client connecting through
an HTTP proxy is `92.40.1.255`, the client requests appear with the public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=5201ee251fbf14300838a3867dd5a0a6c438061d79dcc1f407a770648320abb0 url=/mulesoft/current/en-us/gateway/1.13/policies-included-ip-blocklist.md -->

---
product: Omni Gateway
version: 1.13
keywords: ip, blocklist, validation, api gateway, flex gateway, gateway, policy
---

# IP Blocklist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Blocklist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-blocklist-release-notes">IP Blocklist</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Blocklist policy controls access to a configured API endpoint from either a single IP address
or a range of IP addresses.

The IP Blocklist policy restricts access to a protected resource when a match is found between a
source IP (specified when configuring the policy) and either a list of individual IPs or a range of
IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP to be used when the policy tries to determine whether
the IP belongs to the restricted IP list defined in the policy.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ip-blocklist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-blocklist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Blocklist</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Blocklist in the Policy

Specify IP addresses to block in your policy based on:

- The IP address of the request.

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header.

- Any other origin.

### Blocklist Access Based on the IP Address of the Request

Blocklist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the white space, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30` includes
  the consolidated range `192.168.3.0` through `192.168.3.3`.

- Define a whole range of IP addresses by specifying the relevant octets of the IP address that you
  want to permit, for example, setting `192.168` will include IP addresses from `192.168.0.0`
  through `192.168.255.255`.

### Blocklist Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can blocklist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request

For example, if you want to blocklist `192.168.2.3` and the address of a client connecting through
an HTTP proxy is `92.40.1.255`, the client requests appear with the public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=b33b4e1bae8630cb64737090c7e926b48df0874d534b61243c28a89f5b26903a url=/mulesoft/current/en-us/gateway/1.9/policies-included-ip-blocklist.md -->

---
product: Omni Gateway
version: 1.9
keywords: ip, blocklist, validation, api gateway, flex gateway, gateway, policy
---

# IP Blocklist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Blocklist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Blocklist policy controls access to a configured API endpoint from either a single IP address
or a range of IP addresses.

The IP Blocklist policy restricts access to a protected resource when a match is found between a
source IP (specified when configuring the policy) and either a list of individual IPs or a range of
IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP to be used when the policy tries to determine whether
the IP belongs to the restricted IP list defined in the policy.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: ip-blocklist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-blocklist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Blocklist</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Blocklist in the Policy

Specify IP addresses to block in your policy based on:

- The IP address of the request.

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header.

- Any other origin.

### Blocklist Access Based on the IP Address of the Request

Blocklist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the white space, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30` includes
  the consolidated range `192.168.3.0` through `192.168.3.3`.

- Define a whole range of IP addresses by specifying the relevant octets of the IP address that you
  want to permit, for example, setting `192.168` will include IP addresses from `192.168.0.0`
  through `192.168.255.255`.

### Blocklist Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can blocklist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request

For example, if you want to blocklist `192.168.2.3` and the address of a client connecting through
an HTTP proxy is `92.40.1.255`, the client requests appear with the public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=12859b49bd53ddf9977be53f5ec1e4b2e823ef797d921b512fb172ed1db7f8fb url=/mulesoft/current/en-us/gateway/latest/policies-included-ip-blocklist.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: ip, blocklist, validation, api gateway, flex gateway, gateway, policy
---

# IP Blocklist Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>IP Blocklist</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks a single IP address or a range of IP addresses from accessing an API endpoint</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-blocklist-release-notes">IP Blocklist</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - IP is rejected</p></td></tr></tbody></table>

## Summary

The IP Blocklist policy controls access to a configured API endpoint from either a single IP address
or a range of IP addresses.

The IP Blocklist policy restricts access to a protected resource when a match is found between a
source IP (specified when configuring the policy) and either a list of individual IPs or a range of
IPs. The policy supports both IPv4 and IPv6 addresses.

DataWeave 2.0 expressions define the source IP to be used when the policy tries to determine whether
the IP belongs to the restricted IP list defined in the policy.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: ip-blocklist-flex config: ips: <array> // REQUIRED ipExpression: <string> //
OPTIONAL, default: "#\[attributes.headers\['x-forwarded-for'\]\]"

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ips</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p><code>ipExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['x-forwarded-for']]</code></p></div></div></td><td><div><div><p>The DataWeave 2.0 expression to be used for extracting the IP address from this API request</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: ip-blocklist-flex config: ips: - "192.168.1.1" - "192.168.3.1/30" -
"192.168.2" - "192.160"

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>IP expression</p></div></div></td><td><div><div><p>The DataWeave 2.0 expression used for extracting the IP address from this API request.</p></div></div></td></tr><tr><td><div><div><p>Blocklist</p></div></div></td><td><div><div><p>The list of IP addresses blocked from the API. You can define one IP or IP range at a time, as many times as required. For more information, see <a href="#specifying_ip_address">Specifying IP Addresses to Blocklist in the Policy</a>.</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations either to a select few or to all methods and resources of the API.</p></div></div></td></tr></tbody></table>

## Specifying IP Addresses to Blocklist in the Policy

Specify IP addresses to block in your policy based on:

- The IP address of the request.

- The origin IP address that is determined by resolving a specific DataWeave expression, such as the
  [x-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) header.

- Any other origin.

### Blocklist Access Based on the IP Address of the Request

Blocklist access based on the IP address of the request in any of the following ways:

- Define a specific IP address by enumerating it in the white space, for example, `192.168.1.1`.

- Define a subset of addresses by identifying a subnet mask, for example, `192.168.3.1/30` includes
  the consolidated range `192.168.3.0` through `192.168.3.3`.

- Define a whole range of IP addresses by specifying the relevant octets of the IP address that you
  want to permit, for example, setting `192.168` will include IP addresses from `192.168.0.0`
  through `192.168.255.255`.

### Blocklist Access Based on the Origin IP Address of the x-Forwarded-For Header

If the client connects to your API through an HTTP proxy or a load balancer, you can blocklist the
client’s specific IP address (the IP address originating the request) instead of the address that
appears in the request

For example, if you want to blocklist `192.168.2.3` and the address of a client connecting through
an HTTP proxy is `92.40.1.255`, the client requests appear with the public address using the proxy.

Typically, applications use the `X-Forwarded-For` header to identify the origin IP addresses of a
request that was redirected to your endpoint.

You can use a DataWeave 2.0 expression in the policy to instruct the service to look for the IP
address in the `x-Forwarded-For` header.

When you insert the IP address in the IP expression field of the policy parameters, Anypoint
Platform is instructed to look for the starting IP address in the concatenated values of the
`x-Forwarded-For` header of the request.

<!-- document id=59c87567085130cf968a3c6595d2d55069891610e0b89ced7c1c4de112e16282 url=/mulesoft/current/en-us/gateway/latest/policies-included-javascript-scripting.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: javascript, scripting, transformation, request filter, response filter, api gateway, flex gateway, gateway, policy
---

# JavaScript Scripting Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>JavaScript Scripting</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Runs a user-supplied JavaScript module to inspect and modify requests and responses</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Transformation</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>1.14.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/javascript-scripting-release-notes">JavaScript Scripting Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p><code>500</code> - The script threw an error while processing the request or response</p></td></tr></tbody></table>

## Summary

The JavaScript Scripting policy runs a JavaScript module that you supply to inspect and modify HTTP
traffic as it passes through the gateway. Use the policy to add or change headers, transform request
or response bodies, and block a request with an early response.

The module runs as a standard JavaScript ES module and can export either or both of these functions:

- `requestFilter(request)` runs for every incoming request. It can read and modify the request,
  allow the request to continue to the upstream service, or terminate the request with an immediate
  response.

- `responseFilter(response, requestData)` runs for every upstream response. It can read and modify
  the response before the gateway returns it to the client.

The module must export at least one of these functions to properly load.

Module-level variables persist across invocations to share state between requests (for example, to
maintain a counter). The runtime provides the standard `console`, `TextEncoder`, and `TextDecoder`
globals. The script runs synchronously; `async` functions and promises returned from a filter aren’t
awaited.

## Configure Policy Parameters

### Omni Gateway Local Mode

\- policyRef: name: javascript-scripting-flex config: script: <string> // REQUIRED - JavaScript ES
module source

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>script</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>—</p></div></div></td><td><div><div><p>The full source text of a JavaScript ES module. The module must export at least one of <code>requestFilter</code> or <code>responseFilter</code>.</p></div></div></td></tr></tbody></table>

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Policy type</p></div></div></td><td><div><div><p>JavaScript Scripting</p></div></div></td></tr><tr><td><div><div><p>Script</p></div></div></td><td><div><div><p>The JavaScript ES module that exports <code>requestFilter</code> and/or <code>responseFilter</code></p></div></div></td></tr></tbody></table>

## Script API

The gateway calls the exported functions and passes objects that represent the request or response.
These objects can’t be constructed from JavaScript.

### Filter Functions

<table><colgroup><col> <col></colgroup><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>requestFilter(request)</code></p></div></div></td><td><div><div><p>Called for each incoming request. Receives a <code>request</code> object. Returns a flow result that controls whether the request continues to the upstream service or is stopped with an early response. Returning <code>undefined</code> continues the request.</p></div></div></td></tr><tr><td><div><div><p><code>responseFilter(response, requestData)</code></p></div></div></td><td><div><div><p>Called for each upstream response. Receives a <code>response</code> object and the <code>requestData</code> value carried from <code>requestFilter</code>. The return value is ignored.</p></div></div></td></tr></tbody></table>

### Request and Response Objects

Both the `request` and `response` objects expose the same methods to read and modify headers and the
body:

<table><colgroup><col> <col></colgroup><thead><tr><th>Method</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>getHeaders()</code></p></div></div></td><td><div><div><p>Returns all headers as an array of <code>[name, value]</code> pairs.</p></div></div></td></tr><tr><td><div><div><p><code>setHeaders(headers)</code></p></div></div></td><td><div><div><p>Replaces all headers with the provided array of <code>[name, value]</code> pairs.</p></div></div></td></tr><tr><td><div><div><p><code>getHeader(name)</code></p></div></div></td><td><div><div><p>Returns the value of the first header matching <code>name</code> (case-insensitive), or <code>undefined</code> if absent.</p></div></div></td></tr><tr><td><div><div><p><code>setHeader(name, value)</code></p></div></div></td><td><div><div><p>Sets a header, replacing any existing values for that name.</p></div></div></td></tr><tr><td><div><div><p><code>addHeader(name, value)</code></p></div></div></td><td><div><div><p>Appends a header, preserving any existing values for that name.</p></div></div></td></tr><tr><td><div><div><p><code>removeHeader(name)</code></p></div></div></td><td><div><div><p>Removes all headers matching <code>name</code>.</p></div></div></td></tr><tr><td><div><div><p><code>getBody()</code></p></div></div></td><td><div><div><p>Returns the body as a <code>Uint8Array</code>.</p></div></div></td></tr><tr><td><div><div><p><code>setBody(body)</code></p></div></div></td><td><div><div><p>Replaces the body with the provided <code>Uint8Array</code>. Throws an error if the entity has no body or if the body exceeds the 1 MiB maximum.</p></div></div></td></tr><tr><td><div><div><p><code>getBodyString()</code></p></div></div></td><td><div><div><p>Returns the body decoded as a UTF-8 string. Invalid byte sequences are replaced with the Unicode replacement character (<code>U+FFFD</code>).</p></div></div></td></tr><tr><td><div><div><p><code>setBodyString(body)</code></p></div></div></td><td><div><div><p>Replaces the body with the UTF-8 encoding of the provided string. Throws an error if the entity has no body or if the encoded body exceeds the 1 MiB maximum.</p></div></div></td></tr><tr><td><div><div><p><code>containsBody()</code></p></div></div></td><td><div><div><p>Returns <code>true</code> if the entity has a body, or <code>false</code> otherwise. Use this to check whether body operations are safe before you call them.</p></div></div></td></tr></tbody></table>

### Controlling Request Flow

The value that `requestFilter` returns controls whether the request continues:

- Return `undefined` or `{ flow: "continue" }` to allow the request to continue to the upstream
  service.

- Return `{ flow: "continue", data: <value> }` to continue and pass `data` to `responseFilter`. The
  `requestData` argument of `responseFilter` receives `{ flow: "continue", data: <value> }`.

- Return `{ flow: "break", response: { statusCode, headers, body } }` to stop the request and send
  an immediate response to the client. The upstream service is not called. `headers` is an array of
  `[name, value]` pairs, and `body` is optional and can be a `Uint8Array` or a string.

If `requestFilter` returns an unexpected value, the gateway logs a warning and treats it as
continue.

### Error Handling

If a filter function throws an error, the gateway stops processing and returns a `500` response with
the JSON body `{"error":"Internal error"}` to the client. The error is written to the gateway logs.

## Logging

Calls to the `console` methods are written to the gateway logs at the corresponding level:

<table><colgroup><col> <col></colgroup><thead><tr><th>Console method</th><th>Gateway log level</th></tr></thead><tbody><tr><td><div><div><p><code>console.debug()</code></p></div></div></td><td><div><div><p>debug</p></div></div></td></tr><tr><td><div><div><p><code>console.log()</code>, <code>console.info()</code></p></div></div></td><td><div><div><p>info</p></div></div></td></tr><tr><td><div><div><p><code>console.warn()</code></p></div></div></td><td><div><div><p>warn</p></div></div></td></tr><tr><td><div><div><p><code>console.error()</code></p></div></div></td><td><div><div><p>error</p></div></div></td></tr></tbody></table>

## Examples

### Add and Remove Headers

This example adds a header to the request and the response, and removes a header from each:

\- policyRef: name: javascript-scripting-flex config: script: | export function
requestFilter(request) { request.setHeader("x-processed-by", "javascript-policy");
request.removeHeader("x-internal"); }

      export function responseFilter(response) {
        response.setHeader("x-served-by", "omni-gateway");
        response.removeHeader("server");
      }

### Block a Request with an Early Response

This example rejects a request that is missing an API key and returns a `401` response without
calling the upstream service:

\- policyRef: name: javascript-scripting-flex config: script: | export function
requestFilter(request) { if (!request.getHeader("x-api-key")) { return { flow: "break", response: {
statusCode: 401, headers: \[\["content-type", "text/plain"\]\], body: "Missing API key", }, }; } }

### Pass Data from the Request to the Response

This example reads a value during the request phase and uses it during the response phase:

\- policyRef: name: javascript-scripting-flex config: script: | export function
requestFilter(request) { const id = request.getHeader("x-request-id") || "unknown"; return { flow:
"continue", data: { id } }; }

      export function responseFilter(response, requestData) {
        if (requestData.flow === "continue" && requestData.data) {
          response.setHeader("x-request-id", requestData.data.id);
        }
      }

### Transform the Response Body

This example replaces the response body with a new string:

\- policyRef: name: javascript-scripting-flex config: script: | export function
responseFilter(response) { if (response.containsBody()) {
response.setBodyString('{"message":"transformed by gateway"}'); response.setHeader("content-type",
"application/json"); } }

<!-- document id=9bda9278a171a0d917b3c1801eaef8c60dac750c3658ab1dd60a8b93ca2955ae url=/mulesoft/current/en-us/gateway/1.12/policies-included-json-threat-protection.md -->

---
product: Omni Gateway
version: 1.12
keywords: json threat protection, api gateway, flex gateway, gateway, policy
---

# JSON Threat Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>JSON Threat Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Protects against malicious JSON in API requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request</p></td></tr></tbody></table>

## Summary

Applications processing JSON requests are susceptible to attacks characterized by unusual inflation
of elements and nesting levels. Attackers use recursive techniques to consume memory resources.
Dramatic swings in the size of the application data often signal a security problem. The JSON Threat
Protection policy helps protect your applications from such intrusions.

If you find that attacks on your Anypoint Platform setup are difficult to detect, design your
services architecture with layers of protection in addition to JSON Threat Protection.

> [!NOTE] The JSON Threat Protection policy doesn’t support multi-part form requests.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: json-threat-protection-flex config: maxContainerDepth: <int> // OPTIONAL
maxObjectEntryCount: <int> // OPTIONAL maxObjectEntryNameLength: <int> // OPTIONAL
maxArrayElementCount: <int> // OPTIONAL maxStringValueLength: <int> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxContainerDepth</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of entries in an object. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryNameLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string length of an object’s entry name. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxArrayElementCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of elements in an array. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxStringValueLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string value length. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: json-threat-protection-flex
  config:
    maxContainerDepth: 10
    maxObjectEntryCount: 10000
    maxObjectEntryNameLength: 80
    maxArrayElementCount: 10000
    maxStringValueLength: 255
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><p><strong>Field</strong></p></td><td><p><strong>Description</strong></p></td><td><p><strong>Default</strong></p></td><td><p><strong>Required</strong></p></td></tr><tr><td><p>Maximum Container Depth</p></td><td><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>Specifies the maximum length of a string value</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>Specifies the maximum string length of an object’s entry name</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>Specifies the maximum number of entries in an object</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>Specifies the maximum number of elements in an array</p></td><td><p>-1</p></td><td><p>false</p></td></tr></tbody></table>

> [!NOTE] A value of -1 indicates that the field value has no limits.

## Payload Example

If your payload contains the following example JSON:

{ "Players":\[ { "Name":"Sachin", "Email":"sachin.tendulkar@example.com" }, { "Name":"Suryakumar",
"email":"Surya@example.com" }, { "Name":"Bhuvi", "email":"bhuvi@example.com" }, { "Name":"Jonty",
"Email":"jonty@example.com" } \] }

The policy defines the example parameter values as follows:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Value</th><th>Explanation</th></tr></thead><tbody><tr><td><p>Maximum Container Depth</p></td><td><p>3</p></td><td><p>The depth of the <code>Name</code> and <code>Email</code> entries</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>28</p></td><td><p>The length of <code>sachin.tendulkar@example.com</code></p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>7</p></td><td><p>The length of the <code>Players</code> object entry name</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>2</p></td><td><p>The number of entries in each <code>Players</code> object</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>4</p></td><td><p>The number of elements in the <code>Players</code> array</p></td></tr></tbody></table>

<!-- document id=590037c2d160498e276c2e0481147bb42d26494be5e9c93849487cfd0f36f295 url=/mulesoft/current/en-us/gateway/1.13/policies-included-json-threat-protection.md -->

---
product: Omni Gateway
version: 1.13
keywords: json threat protection, api gateway, flex gateway, gateway, policy
---

# JSON Threat Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>JSON Threat Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Protects against malicious JSON in API requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/json-threat-protection-release-notes">JSON Threat Protection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request</p></td></tr></tbody></table>

## Summary

Applications processing JSON requests are susceptible to attacks characterized by unusual inflation
of elements and nesting levels. Attackers use recursive techniques to consume memory resources.
Dramatic swings in the size of the application data often signal a security problem. The JSON Threat
Protection policy helps protect your applications from such intrusions.

If you find that attacks on your Anypoint Platform setup are difficult to detect, design your
services architecture with layers of protection in addition to JSON Threat Protection.

> [!NOTE] The JSON Threat Protection policy doesn’t support multi-part form requests.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: json-threat-protection-flex config: maxContainerDepth: <int> // OPTIONAL
maxObjectEntryCount: <int> // OPTIONAL maxObjectEntryNameLength: <int> // OPTIONAL
maxArrayElementCount: <int> // OPTIONAL maxStringValueLength: <int> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxContainerDepth</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of entries in an object. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryNameLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string length of an object’s entry name. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxArrayElementCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of elements in an array. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxStringValueLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string value length. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: json-threat-protection-flex
  config:
    maxContainerDepth: 10
    maxObjectEntryCount: 10000
    maxObjectEntryNameLength: 80
    maxArrayElementCount: 10000
    maxStringValueLength: 255
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><p><strong>Field</strong></p></td><td><p><strong>Description</strong></p></td><td><p><strong>Default</strong></p></td><td><p><strong>Required</strong></p></td></tr><tr><td><p>Maximum Container Depth</p></td><td><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>Specifies the maximum length of a string value</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>Specifies the maximum string length of an object’s entry name</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>Specifies the maximum number of entries in an object</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>Specifies the maximum number of elements in an array</p></td><td><p>-1</p></td><td><p>false</p></td></tr></tbody></table>

> [!NOTE] A value of -1 indicates that the field value has no limits.

## Payload Example

If your payload contains the following example JSON:

{ "Players":\[ { "Name":"Sachin", "Email":"sachin.tendulkar@example.com" }, { "Name":"Suryakumar",
"email":"Surya@example.com" }, { "Name":"Bhuvi", "email":"bhuvi@example.com" }, { "Name":"Jonty",
"Email":"jonty@example.com" } \] }

The policy defines the example parameter values as follows:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Value</th><th>Explanation</th></tr></thead><tbody><tr><td><p>Maximum Container Depth</p></td><td><p>3</p></td><td><p>The depth of the <code>Name</code> and <code>Email</code> entries</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>28</p></td><td><p>The length of <code>sachin.tendulkar@example.com</code></p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>7</p></td><td><p>The length of the <code>Players</code> object entry name</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>2</p></td><td><p>The number of entries in each <code>Players</code> object</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>4</p></td><td><p>The number of elements in the <code>Players</code> array</p></td></tr></tbody></table>

<!-- document id=727d46c14a5602d85b3f0c7029426531f168c1c66cbcf900d4606efe5dedfac4 url=/mulesoft/current/en-us/gateway/1.9/policies-included-json-threat-protection.md -->

---
product: Omni Gateway
version: 1.9
keywords: json threat protection, api gateway, flex gateway, gateway, policygit@github.com:mulesoft-emu/docs-site-playbook.git
---

# JSON Threat Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>JSON Threat Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Protects against malicious JSON in API requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request</p></td></tr></tbody></table>

## Summary

Applications processing JSON requests are susceptible to attacks characterized by unusual inflation
of elements and nesting levels. Attackers use recursive techniques to consume memory resources.
Dramatic swings in the size of the application data often signal a security problem. The JSON Threat
Protection policy helps protect your applications from such intrusions.

If you find that attacks on your Anypoint Platform setup are difficult to detect, design your
services architecture with layers of protection in addition to JSON Threat Protection.

> [!NOTE] The JSON Threat Protection policy doesn’t support multi-part form requests.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: json-threat-protection-flex config: maxContainerDepth: <int> // OPTIONAL
maxObjectEntryCount: <int> // OPTIONAL maxObjectEntryNameLength: <int> // OPTIONAL
maxArrayElementCount: <int> // OPTIONAL maxStringValueLength: <int> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxContainerDepth</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of entries in an object. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryNameLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string length of an object’s entry name. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxArrayElementCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of elements in an array. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxStringValueLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string value length. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: json-threat-protection-flex
  config:
    maxContainerDepth: 10
    maxObjectEntryCount: 10000
    maxObjectEntryNameLength: 80
    maxArrayElementCount: 10000
    maxStringValueLength: 255
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><p><strong>Field</strong></p></td><td><p><strong>Description</strong></p></td><td><p><strong>Default</strong></p></td><td><p><strong>Required</strong></p></td></tr><tr><td><p>Maximum Container Depth</p></td><td><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>Specifies the maximum length of a string value</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>Specifies the maximum string length of an object’s entry name</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>Specifies the maximum number of entries in an object</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>Specifies the maximum number of elements in an array</p></td><td><p>-1</p></td><td><p>false</p></td></tr></tbody></table>

> [!NOTE] A value of -1 indicates that the field value has no limits.

## Payload Example

If your payload contains the following example JSON:

{ "Players":\[ { "Name":"Sachin", "Email":"sachin.tendulkar@example.com" }, { "Name":"Suryakumar",
"email":"Surya@example.com" }, { "Name":"Bhuvi", "email":"bhuvi@example.com" }, { "Name":"Jonty",
"Email":"jonty@example.com" } \] }

The policy defines the example parameter values as follows:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Value</th><th>Explanation</th></tr></thead><tbody><tr><td><p>Maximum Container Depth</p></td><td><p>3</p></td><td><p>The depth of the <code>Name</code> and <code>Email</code> entries</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>28</p></td><td><p>The length of <code>sachin.tendulkar@example.com</code></p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>7</p></td><td><p>The length of the <code>Players</code> object entry name</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>2</p></td><td><p>The number of entries in each <code>Players</code> object</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>4</p></td><td><p>The number of elements in the <code>Players</code> array</p></td></tr></tbody></table>

<!-- document id=bf97e51222d7ac31bfba606276406ad9403b6ac40e9a86e568184fbfded236d4 url=/mulesoft/current/en-us/gateway/latest/policies-included-json-threat-protection.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: json threat protection, api gateway, flex gateway, gateway, policy
---

# JSON Threat Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>JSON Threat Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Protects against malicious JSON in API requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/json-threat-protection-release-notes">JSON Threat Protection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request</p></td></tr></tbody></table>

## Summary

Applications processing JSON requests are susceptible to attacks characterized by unusual inflation
of elements and nesting levels. Attackers use recursive techniques to consume memory resources.
Dramatic swings in the size of the application data often signal a security problem. The JSON Threat
Protection policy helps protect your applications from such intrusions.

If you find that attacks on your Anypoint Platform setup are difficult to detect, design your
services architecture with layers of protection in addition to JSON Threat Protection.

> [!NOTE] The JSON Threat Protection policy doesn’t support multi-part form requests.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: json-threat-protection-flex config: maxContainerDepth: <int> // OPTIONAL
maxObjectEntryCount: <int> // OPTIONAL maxObjectEntryNameLength: <int> // OPTIONAL
maxArrayElementCount: <int> // OPTIONAL maxStringValueLength: <int> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxContainerDepth</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of entries in an object. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxObjectEntryNameLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string length of an object’s entry name. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxArrayElementCount</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of elements in an array. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr><tr><td><div><div><p><code>maxStringValueLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum string value length. Specifying -1 indicates that the field value has no limits.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: json-threat-protection-flex
  config:
    maxContainerDepth: 10
    maxObjectEntryCount: 10000
    maxObjectEntryNameLength: 80
    maxArrayElementCount: 10000
    maxStringValueLength: 255
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><p><strong>Field</strong></p></td><td><p><strong>Description</strong></p></td><td><p><strong>Default</strong></p></td><td><p><strong>Required</strong></p></td></tr><tr><td><p>Maximum Container Depth</p></td><td><p>Specifies the maximum nested depth. JSON allows you to nest the containers (object and array) in any order to any depth</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>Specifies the maximum length of a string value</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>Specifies the maximum string length of an object’s entry name</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>Specifies the maximum number of entries in an object</p></td><td><p>-1</p></td><td><p>false</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>Specifies the maximum number of elements in an array</p></td><td><p>-1</p></td><td><p>false</p></td></tr></tbody></table>

> [!NOTE] A value of -1 indicates that the field value has no limits.

## Payload Example

If your payload contains the following example JSON:

{ "Players":\[ { "Name":"Sachin", "Email":"sachin.tendulkar@example.com" }, { "Name":"Suryakumar",
"email":"Surya@example.com" }, { "Name":"Bhuvi", "email":"bhuvi@example.com" }, { "Name":"Jonty",
"Email":"jonty@example.com" } \] }

The policy defines the example parameter values as follows:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Value</th><th>Explanation</th></tr></thead><tbody><tr><td><p>Maximum Container Depth</p></td><td><p>3</p></td><td><p>The depth of the <code>Name</code> and <code>Email</code> entries</p></td></tr><tr><td><p>Maximum String Value Length</p></td><td><p>28</p></td><td><p>The length of <code>sachin.tendulkar@example.com</code></p></td></tr><tr><td><p>Maximum Object Entry Name Length</p></td><td><p>7</p></td><td><p>The length of the <code>Players</code> object entry name</p></td></tr><tr><td><p>Maximum Object Entry Count</p></td><td><p>2</p></td><td><p>The number of entries in each <code>Players</code> object</p></td></tr><tr><td><p>Maximum Array Element Count</p></td><td><p>4</p></td><td><p>The number of elements in the <code>Players</code> array</p></td></tr></tbody></table>

<!-- document id=1529c0b74bdb44d6453937cdf114f01ace2dc3c794ac2ebd851ed56d3dfbd3e2 url=/mulesoft/current/en-us/gateway/1.12/policies-included-jwt-validation.md -->

---
product: Omni Gateway
version: 1.12
keywords: jwt validation, api gateway, flex gateway, gateway, policy
---

# JWT Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>JWT Validation</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Validates a JWT</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>400 - Token was not provided in the request.</p></div><table><colgroup><col> <col></colgroup><tbody><tr><td rowspan="3"><div><div><p>401</p></div></div></td><td><div><div><p>Signature was not validated, or is invalid.</p></div></div></td></tr><tr><td><div><div><p>Some of the required claims are not present or their validation failed.</p></div></div></td></tr><tr><td><div><div><p>Failed to parse the token.</p></div></div></td></tr></tbody></table></div></td></tr></tbody></table>

## Summary

JSON Web Token (JWT) is a URL-secure method of representing claims to be transferred between two
parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web
Signature (JWS), or as a JSON web encryption (JWE) structure in plain text. This enables the claims
to be digitally signed and integrity protected with a message authentication code (MAC). Because the
token is signed, you can trust the information and its source.

The JWT Validation policy validates the signature of the token and asserts the values of the claims
of all incoming requests by using a JWT with JWS format. The policy does not validate JWT that uses
JWE.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: jwt-validation-flex config:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>signingMethod</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>rsa</code></p></div></div></td><td><div><div><p>String containing the key signing method. Supported values: <code>rsa</code>, <code>hmac</code>, <code>es</code>, <code>none</code></p></div></div></td></tr><tr><td><div><div><p><code>signingKeyLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>256</p></div></div></td><td><div><div><p>Number indicating key length. Supported values are 256, 384, 512. For ES method, Flex Gateway supports 256 and 384 key lengths.</p></div></div></td></tr><tr><td><div><div><p><code>textKey</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>your-(256|384|512)-bit-secret/your-public-pem-certificate</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>httpBearerAuthenticationHeader</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtKeyOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>text</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwksUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code><a href="http://your-jwks-service.example:80/base/path">http://your-jwks-service.example:80/base/path</a></code></p></div></div></td><td><div><div><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceTimeToLive</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Amount of time, in minutes, during which the policy considers the JWKS valid.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceConnectionTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.</p></div></div></td></tr><tr><td><div><div><p><code>validateAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryNbfClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryExpClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>supportedAudiences</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>validateCustomClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>nonMandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['jwt']]</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>This parameter must be set to <code>true</code> in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>clientIdExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[vars.claimSet.client_id]</code></p></div></div></td><td><div></div></td></tr></tbody></table>

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p>JWT Origin</p></td><td><p>Specifies from where in the request the JWT will be extracted: * HTTP Bearer Authentication Header * Custom Expression</p><p>If you set this field to <code>HTTP Bearer Authentication Header</code>, the JWT is expected as Bearer.<br>If you set this field to <code>Custom Expression</code>, provide a DataWeave expression that returns the token.</p></td><td></td></tr><tr><td><p>Token Expression</p></td><td><p>If you set the JWT Origin to <code>Custom Expression</code>, type the DataWeave expression returning the JWT here.</p></td><td><p><code>#[attributes.headers['jwt']]</code><br>This expression searches the JWT in the header named <code>jwt</code>.</p></td></tr><tr><td><p>JWT Signing Method</p></td><td><p>Specify the signing method expected in the incoming JWT. The policy rejects the token if the JWT has a different signing method.</p></td><td><p>RSA, HMAC, ES, None</p></td></tr><tr><td><p>JWT Signing Key Length</p></td><td><p>Specify the length of the key (in the case of the HMAC algorithm) or the algorithm (in the case of RSA) used for the signing method.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>256, 384, 512. For ES method, Flex Gateway only supports 256 and 384 key lengths.</p></td></tr><tr><td><p>JWT Key Origin</p></td><td><p>Specifies where to obtain the key for the Signature validation.<br>You can provide the key in the policy by selecting the <strong>Text</strong> option or by obtaining it from a <strong>JWKS</strong>.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td></td></tr><tr><td><p>JWT Key</p></td><td><p>This field appears if you selected <strong>Text</strong> as JWT Key Origin.<br>Use this field to provide the key used to check the signature of the token.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>Enter a 32, 48, or 64 character string shared secret for HMAC, a 32 character string shared secret for ES, or the PEM Public Key without the header and footer for RSA.</p></td></tr><tr><td><p>JWKS URL</p></td><td><p>This field appears if you selected the <strong>JWKS</strong> method as JWT Key Origin.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></td></tr><tr><td><p>JWKS Caching Time To Live</p></td><td><p>Amount of time, in minutes, that the JWKS is valid. When the JWKS expires, the policy retrieves the JWKS from each JWKS server again. The default value is 60 minutes.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>This field input is the amount of time, in minutes, during which the policy considers the JWKS valid.</p></td></tr><tr><td><p>JWKS Service connection timeout (milliseconds)</p></td><td><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.<br>The default value is 10 seconds.</p></td><td></td></tr><tr><td><p>Skip Client ID Validation</p></td><td><p>If you check this field, the policy does not verify that the client ID extracted from the JWT matches a valid client application of the API.</p></td><td></td></tr><tr><td><p>Client ID Expression</p></td><td><p>If Skip Client Id Validation is not set, the client ID needs to be extracted from the token.</p></td><td><p>By default, the value will be extracted using the expression <code>#[vars.claimSet.client_id]</code> as specified in the <a href="https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16#section-4.3" target="_blank" rel="noopener">Oauth 2.0 token exchange draft</a>.</p></td></tr><tr><td><p>Validate Audience Claim</p></td><td><p>Indicates that the policy should check for the validity of the audience claim. You can set this "Mandatory" if you select <strong>Audience Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Expiration Claim</p></td><td><p>Indicates that the policy should check for the validity of the expiration claim. You can set this claim as "Mandatory" by selecting <strong>Expiration Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Not Before Claim</p></td><td><p>Indicates that the policy should check for the validity of the Not Before claim. You can set this claim as "Mandatory" by selecting <strong>Not Before Claim Mandatory</strong></p></td><td></td></tr><tr><td><p>Validate Custom Claim</p></td><td><p>Enables the usage of custom validations in the policy. The JWT will be valid only if all DataWeave expressions are fulfilled.</p></td><td><p>The policy provides a <em>claimSet</em> variable that contains all the claims present in the incoming JWT. For example:</p><p><code>foo : #[vars.claimSet.foo == 'fooValue']</code></p><p>Note that all DataWeave expressions must return a boolean value or they will always fail.</p></td></tr></tbody></table>

## How This Policy Works

The policy validates claims and signatures differently, as explained in this section.

### Validating Signatures

The policy validates the signature of the JWT based on the values specified in the policy
configuration. If the algorithm specified in the policy configuration does not match with the token,
or if the signature of the token is invalid, all JWTs are rejected by the policy. If no algorithm is
specified, the policy matches every signed and unsigned token.

The algorithms that support signature verification are:

- **Symmetric algorithms** - HMAC using SHA-256, SHA-384, and SHA-512.

- **Asymmetric algorithms** - ES and RSA using SHA-256, SHA-384, and SHA-512.

- **None** - No signature validation.

For more information about the algorithms in a JWS structure, refer to the
[JWA RFC standard](https://tools.ietf.org/html/rfc7518#section-3.1).

### Validating Claims

Claim validations enable you to choose the conditions under which a token received in the policy is
rejected. The following registered claim validations are provided by default:

- **aud**: The Audience validation specifies that a token must be rejected if it does not contain at
  least one of the values defined.

- **exp**: The Expiration validation specifies that a token must be rejected if its date is past the
  validation date.

- **nbf**: The Not before validation specifies that the token must be rejected if the validation
  time is before the time the token has.

In addition to these _provided claims_, you can also specify other claims to use in your
validations. For all claims, _Registered_ or _Custom_, you must provide the following details:

- The name of the claim you want to validate.  
  For example **iss**, for the issuer of the token.

- The value used to test.  
  You can provide a simple literal value if you only need to verify it, or you can provide a
  DataWeave expression for more complex comparisons.

You can define each claim validation as mandatory or non-mandatory. If a claim is defined as
mandatory and is not present in the incoming JWT, the policy rejects this token. If a claim is
defined as non-mandatory and is not present in the incoming JWT, the policy does not reject the
token for that specific validation.  
For both cases, if a claim is present, the policy validates the token value. If the validation
fails, the JWT will be rejected.

### Propagating Claims

After the policy parses and validates the JWT, the claims are propagated to downstream policies and
flows through the **claims** property in the authentication object.

To access the claim values you can use the following Dataweave 2.0 expression by replacing
`<claimName>` with the name of the desired claim to access:

`#[authentication.properties.claims.<claimName>]`

The JWT is also propagated downstream, and you can access it by using the following Dataweave 2.0
expression:

`#[authentication.properties.jwt]`

#### Propagating Client ID

If Client ID validation is enabled, the Client ID is propagated as a claim and as a reserved
authentication property. Access the property by using the following DataWeave expression:

`#[authentication.clientId]`

### Retry Mechanism

If you selected JSON Web Key Set (JWKS) as JWT Key Origin, the policy uses a retry mechanism to
handle failed JWKS fetches. Every time the cached JWKS expires or is absent and a new request is
triggered, a request is sent to each JWKS service. If a request fails, a sequence of asynchronous
requests with an exponential backoff delay is sent to the failed JWKS service until a new JWKS is
obtained and cached again.

Until the recaching finishes, the expired JWKS is used to process the request, and a `503` error is
returned if no request is found. Using an expired JWKS enables you to apply cached values in
upcoming requests, even if the previous requests failed.

## Obtain a Policy Compatible PEM Public Key

If you have a preexisting RSA key in an unsupported format that you want to use, first covert the
key to a PEM public key. The JWT policy uses public RSA key in PEM format.

**Task Prerequisite**

Before you convert your existing key:

1.  Obtain the `public.pem` key.

2.  Before you paste the key to the policy configuration, remove the **\-----BEGIN PUBLIC KEY-----**
    header and the **\-----END PUBLIC KEY-----** footer.

The following table provides instructions for how to convert your existing key based on its current
format:

<table><colgroup><col> <col></colgroup><thead><tr><th>Starting Point</th><th>Procedure</th></tr></thead><tbody><tr><td><div><div><p>No previous certificate</p></div></div></td><td><div><div><ol><li><p>Generate the private RSA key <code>openssl genrsa -out key.pem 2048</code></p></li><li><p>Extract the public key from the generated private key <strong>key.pem</strong> <code>openssl rsa -in key.pem -outform PEM -pubout -out public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>PEM Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the PEM certificate <code>openssl x509 -inform pem -in cert.pem -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>DER Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>x5c field from JWKS</p></div></div></td><td><div><div><ol><li><p>Copy the first certificate from the chain and decode it <code>echo &lt;certificateString&gt; | base64 -D &gt; cert.crt</code> (replace <code>&lt;certificateString&gt;</code> with the copied value)</p></li><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr></tbody></table>

<!-- document id=61a3314fd25d22b9dc29d6c500cdebed5ec8fb76452c2bb7b25fb4fc0537c6ef url=/mulesoft/current/en-us/gateway/1.13/policies-included-jwt-validation.md -->

---
product: Omni Gateway
version: 1.13
keywords: jwt validation, api gateway, flex gateway, gateway, policy
---

# JWT Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>JWT Validation</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Validates a JWT</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/jwt-validation-release-notes">JWT Validation</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>400 - Token was not provided in the request.</p></div><table><colgroup><col> <col></colgroup><tbody><tr><td rowspan="3"><div><div><p>401</p></div></div></td><td><div><div><p>Signature was not validated, or is invalid.</p></div></div></td></tr><tr><td><div><div><p>Some of the required claims are not present or their validation failed.</p></div></div></td></tr><tr><td><div><div><p>Failed to parse the token.</p></div></div></td></tr></tbody></table></div></td></tr></tbody></table>

## Summary

JSON Web Token (JWT) is a URL-secure method of representing claims to be transferred between two
parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web
Signature (JWS), or as a JSON web encryption (JWE) structure in plain text. This enables the claims
to be digitally signed and integrity protected with a message authentication code (MAC). Because the
token is signed, you can trust the information and its source.

The JWT Validation policy validates the signature of the token and asserts the values of the claims
of all incoming requests by using a JWT with JWS format. The policy does not validate JWT that uses
JWE.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: jwt-validation-flex config:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>signingMethod</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>rsa</code></p></div></div></td><td><div><div><p>String containing the key signing method. Supported values: <code>rsa</code>, <code>hmac</code>, <code>es</code>, <code>none</code></p></div></div></td></tr><tr><td><div><div><p><code>signingKeyLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>256</p></div></div></td><td><div><div><p>Number indicating key length. Supported values are 256, 384, 512. For ES method, Omni Gateway supports 256 and 384 key lengths.</p></div></div></td></tr><tr><td><div><div><p><code>textKey</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>your-(256|384|512)-bit-secret/your-public-pem-certificate</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>httpBearerAuthenticationHeader</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtKeyOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>text</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwksUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code><a href="http://your-jwks-service.example:80/base/path">http://your-jwks-service.example:80/base/path</a></code></p></div></div></td><td><div><div><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceTimeToLive</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Amount of time, in minutes, during which the policy considers the JWKS valid.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceConnectionTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.</p></div></div></td></tr><tr><td><div><div><p><code>validateAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryNbfClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryExpClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>supportedAudiences</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>validateCustomClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>nonMandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['jwt']]</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>This parameter must be set to <code>true</code> in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>clientIdExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[vars.claimSet.client_id]</code></p></div></div></td><td><div></div></td></tr></tbody></table>

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p>JWT Origin</p></td><td><p>Specifies from where in the request the JWT will be extracted: * HTTP Bearer Authentication Header * Custom Expression</p><p>If you set this field to <code>HTTP Bearer Authentication Header</code>, the JWT is expected as Bearer.<br>If you set this field to <code>Custom Expression</code>, provide a DataWeave expression that returns the token.</p></td><td></td></tr><tr><td><p>Token Expression</p></td><td><p>If you set the JWT Origin to <code>Custom Expression</code>, type the DataWeave expression returning the JWT here.</p></td><td><p><code>#[attributes.headers['jwt']]</code><br>This expression searches the JWT in the header named <code>jwt</code>.</p></td></tr><tr><td><p>JWT Signing Method</p></td><td><p>Specify the signing method expected in the incoming JWT. The policy rejects the token if the JWT has a different signing method.</p></td><td><p>RSA, HMAC, ES, None</p></td></tr><tr><td><p>JWT Signing Key Length</p></td><td><p>Specify the length of the key (in the case of the HMAC algorithm) or the algorithm (in the case of RSA) used for the signing method.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>256, 384, 512. For ES method, Omni Gateway only supports 256 and 384 key lengths.</p></td></tr><tr><td><p>JWT Key Origin</p></td><td><p>Specifies where to obtain the key for the Signature validation.<br>You can provide the key in the policy by selecting the <strong>Text</strong> option or by obtaining it from a <strong>JWKS</strong>.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td></td></tr><tr><td><p>JWT Key</p></td><td><p>This field appears if you selected <strong>Text</strong> as JWT Key Origin.<br>Use this field to provide the key used to check the signature of the token.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>Enter a 32, 48, or 64 character string shared secret for HMAC, a 32 character string shared secret for ES, or the PEM Public Key without the header and footer for RSA.</p></td></tr><tr><td><p>JWKS URL</p></td><td><p>This field appears if you selected the <strong>JWKS</strong> method as JWT Key Origin.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></td></tr><tr><td><p>JWKS Caching Time To Live</p></td><td><p>Amount of time, in minutes, that the JWKS is valid. When the JWKS expires, the policy retrieves the JWKS from each JWKS server again. The default value is 60 minutes.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>This field input is the amount of time, in minutes, during which the policy considers the JWKS valid.</p></td></tr><tr><td><p>JWKS Service connection timeout (milliseconds)</p></td><td><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.<br>The default value is 10 seconds.</p></td><td></td></tr><tr><td><p>Skip Client ID Validation</p></td><td><p>If you check this field, the policy does not verify that the client ID extracted from the JWT matches a valid client application of the API.</p></td><td></td></tr><tr><td><p>Client ID Expression</p></td><td><p>If Skip Client Id Validation is not set, the client ID needs to be extracted from the token.</p></td><td><p>By default, the value will be extracted using the expression <code>#[vars.claimSet.client_id]</code> as specified in the <a href="https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16#section-4.3" target="_blank" rel="noopener">Oauth 2.0 token exchange draft</a>.</p></td></tr><tr><td><p>Validate Audience Claim</p></td><td><p>Indicates that the policy should check for the validity of the audience claim. You can set this "Mandatory" if you select <strong>Audience Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Expiration Claim</p></td><td><p>Indicates that the policy should check for the validity of the expiration claim. You can set this claim as "Mandatory" by selecting <strong>Expiration Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Not Before Claim</p></td><td><p>Indicates that the policy should check for the validity of the Not Before claim. You can set this claim as "Mandatory" by selecting <strong>Not Before Claim Mandatory</strong></p></td><td></td></tr><tr><td><p>Validate Custom Claim</p></td><td><p>Enables the usage of custom validations in the policy. The JWT will be valid only if all DataWeave expressions are fulfilled.</p></td><td><p>The policy provides a <em>claimSet</em> variable that contains all the claims present in the incoming JWT. For example:</p><p><code>foo : #[vars.claimSet.foo == 'fooValue']</code></p><p>Note that all DataWeave expressions must return a boolean value or they will always fail.</p></td></tr></tbody></table>

## How This Policy Works

The policy validates claims and signatures differently, as explained in this section.

### Validating Signatures

The policy validates the signature of the JWT based on the values specified in the policy
configuration. If the algorithm specified in the policy configuration does not match with the token,
or if the signature of the token is invalid, all JWTs are rejected by the policy. If no algorithm is
specified, the policy matches every signed and unsigned token.

The algorithms that support signature verification are:

- **Symmetric algorithms** - HMAC using SHA-256, SHA-384, and SHA-512.

- **Asymmetric algorithms** - ES and RSA using SHA-256, SHA-384, and SHA-512.

- **None** - No signature validation.

For more information about the algorithms in a JWS structure, refer to the
[JWA RFC standard](https://tools.ietf.org/html/rfc7518#section-3.1).

### Validating Claims

Claim validations enable you to choose the conditions under which a token received in the policy is
rejected. The following registered claim validations are provided by default:

- **aud**: The Audience validation specifies that a token must be rejected if it does not contain at
  least one of the values defined.

- **exp**: The Expiration validation specifies that a token must be rejected if its date is past the
  validation date.

- **nbf**: The Not before validation specifies that the token must be rejected if the validation
  time is before the time the token has.

In addition to these _provided claims_, you can also specify other claims to use in your
validations. For all claims, _Registered_ or _Custom_, you must provide the following details:

- The name of the claim you want to validate.  
  For example **iss**, for the issuer of the token.

- The value used to test.  
  You can provide a simple literal value if you only need to verify it, or you can provide a
  DataWeave expression for more complex comparisons.

You can define each claim validation as mandatory or non-mandatory. If a claim is defined as
mandatory and is not present in the incoming JWT, the policy rejects this token. If a claim is
defined as non-mandatory and is not present in the incoming JWT, the policy does not reject the
token for that specific validation.  
For both cases, if a claim is present, the policy validates the token value. If the validation
fails, the JWT will be rejected.

### Propagating Claims

After the policy parses and validates the JWT, the claims are propagated to downstream policies and
flows through the **claims** property in the authentication object.

To access the claim values you can use the following Dataweave 2.0 expression by replacing
`<claimName>` with the name of the desired claim to access:

`#[authentication.properties.claims.<claimName>]`

The JWT is also propagated downstream, and you can access it by using the following Dataweave 2.0
expression:

`#[authentication.properties.jwt]`

#### Propagating Client ID

If Client ID validation is enabled, the Client ID is propagated as a claim and as a reserved
authentication property. Access the property by using the following DataWeave expression:

`#[authentication.clientId]`

### Retry Mechanism

If you selected JSON Web Key Set (JWKS) as JWT Key Origin, the policy uses a retry mechanism to
handle failed JWKS fetches. Every time the cached JWKS expires or is absent and a new request is
triggered, a request is sent to each JWKS service. If a request fails, a sequence of asynchronous
requests with an exponential backoff delay is sent to the failed JWKS service until a new JWKS is
obtained and cached again.

Until the recaching finishes, the expired JWKS is used to process the request, and a `503` error is
returned if no request is found. Using an expired JWKS enables you to apply cached values in
upcoming requests, even if the previous requests failed.

## Obtain a Policy Compatible PEM Public Key

If you have a preexisting RSA key in an unsupported format that you want to use, first covert the
key to a PEM public key. The JWT policy uses public RSA key in PEM format.

**Task Prerequisite**

Before you convert your existing key:

1.  Obtain the `public.pem` key.

2.  Before you paste the key to the policy configuration, remove the **\-----BEGIN PUBLIC KEY-----**
    header and the **\-----END PUBLIC KEY-----** footer.

The following table provides instructions for how to convert your existing key based on its current
format:

<table><colgroup><col> <col></colgroup><thead><tr><th>Starting Point</th><th>Procedure</th></tr></thead><tbody><tr><td><div><div><p>No previous certificate</p></div></div></td><td><div><div><ol><li><p>Generate the private RSA key <code>openssl genrsa -out key.pem 2048</code></p></li><li><p>Extract the public key from the generated private key <strong>key.pem</strong> <code>openssl rsa -in key.pem -outform PEM -pubout -out public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>PEM Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the PEM certificate <code>openssl x509 -inform pem -in cert.pem -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>DER Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>x5c field from JWKS</p></div></div></td><td><div><div><ol><li><p>Copy the first certificate from the chain and decode it <code>echo &lt;certificateString&gt; | base64 -D &gt; cert.crt</code> (replace <code>&lt;certificateString&gt;</code> with the copied value)</p></li><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr></tbody></table>

<!-- document id=ef86169473cffa32fcbcbd86c0d9ff7f85472b57316e480e6022c4114d7bda37 url=/mulesoft/current/en-us/gateway/1.9/policies-included-jwt-validation.md -->

---
product: Omni Gateway
version: 1.9
keywords: jwt validation, api gateway, flex gateway, gateway, policy
---

# JWT Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>JWT Validation</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Validates a JWT</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>400 - Token was not provided in the request.</p></div><table><colgroup><col> <col></colgroup><tbody><tr><td rowspan="3"><div><div><p>401</p></div></div></td><td><div><div><p>Signature was not validated, or is invalid.</p></div></div></td></tr><tr><td><div><div><p>Some of the required claims are not present or their validation failed.</p></div></div></td></tr><tr><td><div><div><p>Failed to parse the token.</p></div></div></td></tr></tbody></table></div></td></tr></tbody></table>

## Summary

JSON Web Token (JWT) is a URL-secure method of representing claims to be transferred between two
parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web
Signature (JWS), or as a JSON web encryption (JWE) structure in plain text. This enables the claims
to be digitally signed and integrity protected with a message authentication code (MAC). Because the
token is signed, you can trust the information and its source.

The JWT Validation policy validates the signature of the token and asserts the values of the claims
of all incoming requests by using a JWT with JWS format. The policy does not validate JWT that uses
JWE.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: jwt-validation-flex config:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>signingMethod</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>rsa</code></p></div></div></td><td><div><div><p>String containing the key signing method. Supported values: <code>rsa</code>, <code>hmac</code>, <code>es</code>, <code>none</code></p></div></div></td></tr><tr><td><div><div><p><code>signingKeyLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>256</p></div></div></td><td><div><div><p>Number indicating key length. Supported values are 256, 384, 512. For ES method, Flex Gateway supports 256 and 384 key lengths.</p></div></div></td></tr><tr><td><div><div><p><code>textKey</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>your-(256|384|512)-bit-secret/your-public-pem-certificate</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>httpBearerAuthenticationHeader</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtKeyOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>text</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwksUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code><a href="http://your-jwks-service.example:80/base/path">http://your-jwks-service.example:80/base/path</a></code></p></div></div></td><td><div><div><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceTimeToLive</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Amount of time, in minutes, during which the policy considers the JWKS valid.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceConnectionTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.</p></div></div></td></tr><tr><td><div><div><p><code>validateAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryNbfClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryExpClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>supportedAudiences</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>validateCustomClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>nonMandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['jwt']]</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>This parameter must be set to <code>true</code> in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>clientIdExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[vars.claimSet.client_id]</code></p></div></div></td><td><div></div></td></tr></tbody></table>

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p>JWT Origin</p></td><td><p>Specifies from where in the request the JWT will be extracted: * HTTP Bearer Authentication Header * Custom Expression</p><p>If you set this field to <code>HTTP Bearer Authentication Header</code>, the JWT is expected as Bearer.<br>If you set this field to <code>Custom Expression</code>, provide a DataWeave expression that returns the token.</p></td><td></td></tr><tr><td><p>Token Expression</p></td><td><p>If you set the JWT Origin to <code>Custom Expression</code>, type the DataWeave expression returning the JWT here.</p></td><td><p><code>#[attributes.headers['jwt']]</code><br>This expression searches the JWT in the header named <code>jwt</code>.</p></td></tr><tr><td><p>JWT Signing Method</p></td><td><p>Specify the signing method expected in the incoming JWT. The policy rejects the token if the JWT has a different signing method.</p></td><td><p>RSA, HMAC, ES, None</p></td></tr><tr><td><p>JWT Signing Key Length</p></td><td><p>Specify the length of the key (in the case of the HMAC algorithm) or the algorithm (in the case of RSA) used for the signing method.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>256, 384, 512. For ES method, Flex Gateway only supports 256 and 384 key lengths.</p></td></tr><tr><td><p>JWT Key Origin</p></td><td><p>Specifies where to obtain the key for the Signature validation.<br>You can provide the key in the policy by selecting the <strong>Text</strong> option or by obtaining it from a <strong>JWKS</strong>.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td></td></tr><tr><td><p>JWT Key</p></td><td><p>This field appears if you selected <strong>Text</strong> as JWT Key Origin.<br>Use this field to provide the key used to check the signature of the token.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>Enter a 32, 48, or 64 character string shared secret for HMAC, a 32 character string shared secret for ES, or the PEM Public Key without the header and footer for RSA.</p></td></tr><tr><td><p>JWKS URL</p></td><td><p>This field appears if you selected the <strong>JWKS</strong> method as JWT Key Origin.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></td></tr><tr><td><p>JWKS Caching Time To Live</p></td><td><p>Amount of time, in minutes, that the JWKS is valid. When the JWKS expires, the policy retrieves the JWKS from each JWKS server again. The default value is 60 minutes.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>This field input is the amount of time, in minutes, during which the policy considers the JWKS valid.</p></td></tr><tr><td><p>JWKS Service connection timeout (milliseconds)</p></td><td><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.<br>The default value is 10 seconds.</p></td><td></td></tr><tr><td><p>Skip Client ID Validation</p></td><td><p>If you check this field, the policy does not verify that the client ID extracted from the JWT matches a valid client application of the API.</p></td><td></td></tr><tr><td><p>Client ID Expression</p></td><td><p>If Skip Client Id Validation is not set, the client ID needs to be extracted from the token.</p></td><td><p>By default, the value will be extracted using the expression <code>#[vars.claimSet.client_id]</code> as specified in the <a href="https://datatracker.ietf.org/doc/html/draft-ietf-oauth-token-exchange-16" target="_blank" rel="noopener">Oauth 2.0 token exchange draft</a>.</p></td></tr><tr><td><p>Validate Audience Claim</p></td><td><p>Indicates that the policy should check for the validity of the audience claim. You can set this "Mandatory" if you select <strong>Audience Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Expiration Claim</p></td><td><p>Indicates that the policy should check for the validity of the expiration claim. You can set this claim as "Mandatory" by selecting <strong>Expiration Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Not Before Claim</p></td><td><p>Indicates that the policy should check for the validity of the Not Before claim. You can set this claim as "Mandatory" by selecting <strong>Not Before Claim Mandatory</strong></p></td><td></td></tr><tr><td><p>Validate Custom Claim</p></td><td><p>Enables the usage of custom validations in the policy. The JWT will be valid only if all DataWeave expressions are fulfilled.</p></td><td><p>The policy provides a <em>claimSet</em> variable that contains all the claims present in the incoming JWT. For example:</p><p><code>foo : #[vars.claimSet.foo == 'fooValue']</code></p><p>Note that all DataWeave expressions must return a boolean value or they will always fail.</p></td></tr></tbody></table>

## How This Policy Works

The policy validates claims and signatures differently, as explained in this section.

### Validating Signatures

The policy validates the signature of the JWT based on the values specified in the policy
configuration. If the algorithm specified in the policy configuration does not match with the token,
or if the signature of the token is invalid, all JWTs are rejected by the policy. If no algorithm is
specified, the policy matches every signed and unsigned token.

The algorithms that support signature verification are:

- **Symmetric algorithms** - HMAC using SHA-256, SHA-384, and SHA-512.

- **Asymmetric algorithms** - ES and RSA using SHA-256, SHA-384, and SHA-512.

- **None** - No signature validation.

For more information about the algorithms in a JWS structure, refer to the
[JWA RFC standard](https://datatracker.ietf.org/doc/html/rfc7518).

### Validating Claims

Claim validations enable you to choose the conditions under which a token received in the policy is
rejected. The following registered claim validations are provided by default:

- **aud**: The Audience validation specifies that a token must be rejected if it does not contain at
  least one of the values defined.

- **exp**: The Expiration validation specifies that a token must be rejected if its date is past the
  validation date.

- **nbf**: The Not before validation specifies that the token must be rejected if the validation
  time is before the time the token has.

In addition to these _provided claims_, you can also specify other claims to use in your
validations. For all claims, _Registered_ or _Custom_, you must provide the following details:

- The name of the claim you want to validate.  
  For example **iss**, for the issuer of the token.

- The value used to test.  
  You can provide a simple literal value if you only need to verify it, or you can provide a
  DataWeave expression for more complex comparisons.

You can define each claim validation as mandatory or non-mandatory. If a claim is defined as
mandatory and is not present in the incoming JWT, the policy rejects this token. If a claim is
defined as non-mandatory and is not present in the incoming JWT, the policy does not reject the
token for that specific validation.  
For both cases, if a claim is present, the policy validates the token value. If the validation
fails, the JWT will be rejected.

### Propagating Claims

After the policy parses and validates the JWT, the claims are propagated to downstream policies and
flows through the **claims** property in the authentication object.

To access the claim values you can use the following Dataweave 2.0 expression by replacing
`<claimName>` with the name of the desired claim to access:

`#[authentication.properties.claims.<claimName>]`

The JWT is also propagated downstream, and you can access it by using the following Dataweave 2.0
expression:

`#[authentication.properties.jwt]`

#### Propagating Client ID

If Client ID validation is enabled, the Client ID is propagated as a claim and as a reserved
authentication property. Access the property by using the following DataWeave expression:

`#[authentication.clientId]`

### Retry Mechanism

If you selected JSON Web Key Set (JWKS) as JWT Key Origin, the policy uses a retry mechanism to
handle failed JWKS fetches. Every time the cached JWKS expires or is absent and a new request is
triggered, a request is sent to each JWKS service. If a request fails, a sequence of asynchronous
requests with an exponential backoff delay is sent to the failed JWKS service until a new JWKS is
obtained and cached again.

Until the recaching finishes, the expired JWKS is used to process the request, and a `503` error is
returned if no request is found. Using an expired JWKS enables you to apply cached values in
upcoming requests, even if the previous requests failed.

## Obtain a Policy Compatible PEM Public Key

If you have a preexisting RSA key in an unsupported format that you want to use, first covert the
key to a PEM public key. The JWT policy uses public RSA key in PEM format.

**Task Prerequisite**

Before you convert your existing key:

1.  Obtain the `public.pem` key.

2.  Before you paste the key to the policy configuration, remove the **\-----BEGIN PUBLIC KEY-----**
    header and the **\-----END PUBLIC KEY-----** footer.

The following table provides instructions for how to convert your existing key based on its current
format:

<table><colgroup><col> <col></colgroup><thead><tr><th>Starting Point</th><th>Procedure</th></tr></thead><tbody><tr><td><div><div><p>No previous certificate</p></div></div></td><td><div><div><ol><li><p>Generate the private RSA key <code>openssl genrsa -out key.pem 2048</code></p></li><li><p>Extract the public key from the generated private key <strong>key.pem</strong> <code>openssl rsa -in key.pem -outform PEM -pubout -out public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>PEM Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the PEM certificate <code>openssl x509 -inform pem -in cert.pem -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>DER Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>x5c field from JWKS</p></div></div></td><td><div><div><ol><li><p>Copy the first certificate from the chain and decode it <code>echo &lt;certificateString&gt; | base64 -D &gt; cert.crt</code> (replace <code>&lt;certificateString&gt;</code> with the copied value)</p></li><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr></tbody></table>

<!-- document id=bb72e23f2980f9db7043a1c50c3d1157ca8d6ecd0afedb1ce77860e339a5c38e url=/mulesoft/current/en-us/gateway/latest/policies-included-jwt-validation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: jwt validation, api gateway, flex gateway, gateway, policy
---

# JWT Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>JWT Validation</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Validates a JWT</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/jwt-validation-release-notes">JWT Validation</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>400 - Token was not provided in the request.</p></div><table><colgroup><col> <col></colgroup><tbody><tr><td rowspan="3"><div><div><p>401</p></div></div></td><td><div><div><p>Signature was not validated, or is invalid.</p></div></div></td></tr><tr><td><div><div><p>Some of the required claims are not present or their validation failed.</p></div></div></td></tr><tr><td><div><div><p>Failed to parse the token.</p></div></div></td></tr></tbody></table></div></td></tr></tbody></table>

## Summary

JSON Web Token (JWT) is a URL-secure method of representing claims to be transferred between two
parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web
Signature (JWS), or as a JSON web encryption (JWE) structure in plain text. This enables the claims
to be digitally signed and integrity protected with a message authentication code (MAC). Because the
token is signed, you can trust the information and its source.

The JWT Validation policy validates the signature of the token and asserts the values of the claims
of all incoming requests by using a JWT with JWS format. The policy does not validate JWT that uses
JWE.

## Use the Policy in Agent Network

Agent Network uses Omni Gateway. The latest policy definition version of the JWT Validation policy
for Omni Gateway is `0.12.0`. Policy definition versions that start with `1` are for Mule Gateway
and cause an error.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: jwt-validation-flex config:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>signingMethod</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>rsa</code></p></div></div></td><td><div><div><p>String containing the key signing method. Supported values: <code>rsa</code>, <code>hmac</code>, <code>es</code>, <code>none</code></p></div></div></td></tr><tr><td><div><div><p><code>signingKeyLength</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>256</p></div></div></td><td><div><div><p>Number indicating key length. Supported values are 256, 384, 512. For ES method, Omni Gateway supports 256 and 384 key lengths.</p></div></div></td></tr><tr><td><div><div><p><code>textKey</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>your-(256|384|512)-bit-secret/your-public-pem-certificate</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>httpBearerAuthenticationHeader</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtKeyOrigin</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>text</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwksUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code><a href="http://your-jwks-service.example:80/base/path">http://your-jwks-service.example:80/base/path</a></code></p></div></div></td><td><div><div><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceTimeToLive</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Amount of time, in minutes, during which the policy considers the JWKS valid.</p></div></div></td></tr><tr><td><div><div><p><code>jwksServiceConnectionTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.</p></div></div></td></tr><tr><td><div><div><p><code>validateAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryAudClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryNbfClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryExpClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>supportedAudiences</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>validateCustomClaim</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>mandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>nonMandatoryCustomClaims</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>jwtExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.headers['jwt']]</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>This parameter must be set to <code>true</code> in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>clientIdExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[vars.claimSet.client_id]</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>enableProtectedResourceMetadata</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Serves the OAuth 2.0 Protected Resource Metadata document at <code>{API_Path}/.well-known/oauth-protected-resource</code> and includes a <code>resource_metadata</code> hint in <code>401</code> responses, per <a href="https://datatracker.ietf.org/doc/html/rfc9728" target="_blank" rel="noopener">RFC 9728</a>.</p></div></div></td></tr><tr><td><div><div><p><code>protectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div><div><p>The authorization server base URL to advertise in the protected resource metadata, for example, <code><a href="https://auth.example.com/realms/myrealm">https://auth.example.com/realms/myrealm</a></code>. This parameter is required when <code>enableProtectedResourceMetadata</code> is <code>true</code> and must be a valid URL. The JWT Validation policy has no issuer to derive this URL from, so you must set it explicitly.</p></div></div></td></tr></tbody></table>

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p>JWT Origin</p></td><td><p>Specifies from where in the request the JWT will be extracted: * HTTP Bearer Authentication Header * Custom Expression</p><p>If you set this field to <code>HTTP Bearer Authentication Header</code>, the JWT is expected as Bearer.<br>If you set this field to <code>Custom Expression</code>, provide a DataWeave expression that returns the token.</p></td><td></td></tr><tr><td><p>Token Expression</p></td><td><p>If you set the JWT Origin to <code>Custom Expression</code>, type the DataWeave expression returning the JWT here.</p></td><td><p><code>#[attributes.headers['jwt']]</code><br>This expression searches the JWT in the header named <code>jwt</code>.</p></td></tr><tr><td><p>JWT Signing Method</p></td><td><p>Specify the signing method expected in the incoming JWT. The policy rejects the token if the JWT has a different signing method.</p></td><td><p>RSA, HMAC, ES, None</p></td></tr><tr><td><p>JWT Signing Key Length</p></td><td><p>Specify the length of the key (in the case of the HMAC algorithm) or the algorithm (in the case of RSA) used for the signing method.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>256, 384, 512. For ES method, Omni Gateway only supports 256 and 384 key lengths.</p></td></tr><tr><td><p>JWT Key Origin</p></td><td><p>Specifies where to obtain the key for the Signature validation.<br>You can provide the key in the policy by selecting the <strong>Text</strong> option or by obtaining it from a <strong>JWKS</strong>.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td></td></tr><tr><td><p>JWT Key</p></td><td><p>This field appears if you selected <strong>Text</strong> as JWT Key Origin.<br>Use this field to provide the key used to check the signature of the token.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>Enter a 32, 48, or 64 character string shared secret for HMAC, a 32 character string shared secret for ES, or the PEM Public Key without the header and footer for RSA.</p></td></tr><tr><td><p>JWKS URL</p></td><td><p>This field appears if you selected the <strong>JWKS</strong> method as JWT Key Origin.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>JWKS server URLs that contain the public keys for the signature validation. Configure multiple JWKS servers with a comma-separated list of the URLs.</p></td></tr><tr><td><p>JWKS Caching Time To Live</p></td><td><p>Amount of time, in minutes, that the JWKS is valid. When the JWKS expires, the policy retrieves the JWKS from each JWKS server again. The default value is 60 minutes.<br>Ignore this field if you selected <strong>none</strong> as JWT Signing Method.</p></td><td><p>This field input is the amount of time, in minutes, during which the policy considers the JWKS valid.</p></td></tr><tr><td><p>JWKS Service connection timeout (milliseconds)</p></td><td><p>Maximum time, in milliseconds, to wait for a response from each JWKS service when authenticating the access token validation endpoint.<br>The default value is 10 seconds.</p></td><td></td></tr><tr><td><p>Skip Client ID Validation</p></td><td><p>If you check this field, the policy does not verify that the client ID extracted from the JWT matches a valid client application of the API.</p></td><td></td></tr><tr><td><p>Client ID Expression</p></td><td><p>If Skip Client Id Validation is not set, the client ID needs to be extracted from the token.</p></td><td><p>By default, the value will be extracted using the expression <code>#[vars.claimSet.client_id]</code> as specified in the <a href="https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16#section-4.3" target="_blank" rel="noopener">Oauth 2.0 token exchange draft</a>.</p></td></tr><tr><td><p>Validate Audience Claim</p></td><td><p>Indicates that the policy should check for the validity of the audience claim. You can set this "Mandatory" if you select <strong>Audience Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Expiration Claim</p></td><td><p>Indicates that the policy should check for the validity of the expiration claim. You can set this claim as "Mandatory" by selecting <strong>Expiration Claim Mandatory</strong>.</p></td><td></td></tr><tr><td><p>Validate Not Before Claim</p></td><td><p>Indicates that the policy should check for the validity of the Not Before claim. You can set this claim as "Mandatory" by selecting <strong>Not Before Claim Mandatory</strong></p></td><td></td></tr><tr><td><p>Validate Custom Claim</p></td><td><p>Enables the usage of custom validations in the policy. The JWT will be valid only if all DataWeave expressions are fulfilled.</p></td><td><p>The policy provides a <em>claimSet</em> variable that contains all the claims present in the incoming JWT. For example:</p><p><code>foo : #[vars.claimSet.foo == 'fooValue']</code></p><p>Note that all DataWeave expressions must return a boolean value or they will always fail.</p></td></tr><tr><td><p>Enable Protected Resource Metadata</p></td><td><p>If you check this field, the policy serves the OAuth 2.0 Protected Resource Metadata document at <code>{API_Path}/.well-known/oauth-protected-resource</code> and includes a <code>resource_metadata</code> hint in <code>401</code> responses, per <a href="https://datatracker.ietf.org/doc/html/rfc9728" target="_blank" rel="noopener">RFC 9728</a>.</p></td><td></td></tr><tr><td><p>Protected Resource Metadata Authorization Server URL</p></td><td><p>The authorization server base URL to advertise in the protected resource metadata. This field is required when <strong>Enable Protected Resource Metadata</strong> is checked and must be a valid URL.</p></td><td><p><code><a href="https://auth.example.com/realms/myrealm">https://auth.example.com/realms/myrealm</a></code></p></td></tr></tbody></table>

## How This Policy Works

The policy validates claims and signatures differently, as explained in this section.

### Validating Signatures

The policy validates the signature of the JWT based on the values specified in the policy
configuration. If the algorithm specified in the policy configuration does not match with the token,
or if the signature of the token is invalid, all JWTs are rejected by the policy. If no algorithm is
specified, the policy matches every signed and unsigned token.

The algorithms that support signature verification are:

- **Symmetric algorithms** - HMAC using SHA-256, SHA-384, and SHA-512.

- **Asymmetric algorithms** - ES and RSA using SHA-256, SHA-384, and SHA-512.

- **None** - No signature validation.

For more information about the algorithms in a JWS structure, refer to the
[JWA RFC standard](https://tools.ietf.org/html/rfc7518#section-3.1).

### Validating Claims

Claim validations enable you to choose the conditions under which a token received in the policy is
rejected. The following registered claim validations are provided by default:

- **aud**: The Audience validation specifies that a token must be rejected if it does not contain at
  least one of the values defined.

- **exp**: The Expiration validation specifies that a token must be rejected if its date is past the
  validation date.

- **nbf**: The Not before validation specifies that the token must be rejected if the validation
  time is before the time the token has.

In addition to these _provided claims_, you can also specify other claims to use in your
validations. For all claims, _Registered_ or _Custom_, you must provide the following details:

- The name of the claim you want to validate.  
  For example **iss**, for the issuer of the token.

- The value used to test.  
  You can provide a simple literal value if you only need to verify it, or you can provide a
  DataWeave expression for more complex comparisons.

You can define each claim validation as mandatory or non-mandatory. If a claim is defined as
mandatory and is not present in the incoming JWT, the policy rejects this token. If a claim is
defined as non-mandatory and is not present in the incoming JWT, the policy does not reject the
token for that specific validation.  
For both cases, if a claim is present, the policy validates the token value. If the validation
fails, the JWT will be rejected.

### Propagating Claims

After the policy parses and validates the JWT, the claims are propagated to downstream policies and
flows through the **claims** property in the authentication object.

To access the claim values you can use the following Dataweave 2.0 expression by replacing
`<claimName>` with the name of the desired claim to access:

`#[authentication.properties.claims.<claimName>]`

The JWT is also propagated downstream, and you can access it by using the following Dataweave 2.0
expression:

`#[authentication.properties.jwt]`

#### Propagating Client ID

If Client ID validation is enabled, the Client ID is propagated as a claim and as a reserved
authentication property. Access the property by using the following DataWeave expression:

`#[authentication.clientId]`

### Serving Protected Resource Metadata

When you enable **Enable Protected Resource Metadata**, the policy implements
[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) so that clients can discover the
authorization server that protects the API. The policy then:

- Serves the metadata document at `{API_Path}/.well-known/oauth-protected-resource`, advertising the
  authorization server set in **Protected Resource Metadata Authorization Server URL**.

- Adds a `resource_metadata` hint (realm `JWT Validation Realm`) to the `WWW-Authenticate` header of
  `401` responses.

- Returns `401` instead of `400` when a request omits the `Authorization` header, directing
  unauthenticated clients to the discovery endpoint.

Because the JWT Validation policy has no issuer to derive the authorization server from, you must
set **Protected Resource Metadata Authorization Server URL** to a valid URL when the feature is
enabled, for example,
`[https://auth.example.com/realms/myrealm](https://auth.example.com/realms/myrealm)`. Otherwise, the
policy configuration is rejected.

### Retry Mechanism

If you selected JSON Web Key Set (JWKS) as JWT Key Origin, the policy uses a retry mechanism to
handle failed JWKS fetches. Every time the cached JWKS expires or is absent and a new request is
triggered, a request is sent to each JWKS service. If a request fails, a sequence of asynchronous
requests with an exponential backoff delay is sent to the failed JWKS service until a new JWKS is
obtained and cached again.

Until the recaching finishes, the expired JWKS is used to process the request, and a `503` error is
returned if no request is found. Using an expired JWKS enables you to apply cached values in
upcoming requests, even if the previous requests failed.

## Obtain a Policy Compatible PEM Public Key

If you have a preexisting RSA key in an unsupported format that you want to use, first covert the
key to a PEM public key. The JWT policy uses public RSA key in PEM format.

**Task Prerequisite**

Before you convert your existing key:

1.  Obtain the `public.pem` key.

2.  Before you paste the key to the policy configuration, remove the **\-----BEGIN PUBLIC KEY-----**
    header and the **\-----END PUBLIC KEY-----** footer.

The following table provides instructions for how to convert your existing key based on its current
format:

<table><colgroup><col> <col></colgroup><thead><tr><th>Starting Point</th><th>Procedure</th></tr></thead><tbody><tr><td><div><div><p>No previous certificate</p></div></div></td><td><div><div><ol><li><p>Generate the private RSA key <code>openssl genrsa -out key.pem 2048</code></p></li><li><p>Extract the public key from the generated private key <strong>key.pem</strong> <code>openssl rsa -in key.pem -outform PEM -pubout -out public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>PEM Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the PEM certificate <code>openssl x509 -inform pem -in cert.pem -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>DER Certificate</p></div></div></td><td><div><div><ol><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr><tr><td><div><div><p>x5c field from JWKS</p></div></div></td><td><div><div><ol><li><p>Copy the first certificate from the chain and decode it <code>echo &lt;certificateString&gt; | base64 -D &gt; cert.crt</code> (replace <code>&lt;certificateString&gt;</code> with the copied value)</p></li><li><p>Extract the public key from the DER certificate <code>openssl x509 -inform der -in cert.crt -pubkey -noout &gt; public.pem</code></p></li><li><p>The public key will be in the file public.pem</p></li></ol></div></div></td></tr></tbody></table>

<!-- document id=980c12036468d96871704e5b925dda1acb158b230e92feca2be1d893d86010ff url=/mulesoft/current/en-us/gateway/1.13/policies-included-llm-pii-detection.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, llm, pii, personally identifiable information
---

# LLM PII Detection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>LLM PII Detection Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in OpenAI and Anthropic format LLM requests and responses</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-pii-detection-release-notes">LLM PII Detection</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden</p></td></tr></tbody></table>

## Summary

The LLM Personally Identifiable Information (PII) Detection policy scans OpenAI and Anthropic format
Model Proxy traffic for PII.

The policy inspects incoming request bodies and outgoing response bodies for PII.

When PII is detected, the policy reports a policy violation. For request traffic, you configure
whether to reject the request, log findings, or log masked findings. Response traffic is never
blocked.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The LLM PII Detection policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>PII Types</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Array of built-in PII types to detect. Supported values are <strong>Email</strong>, <strong>US SSN</strong>, <strong>Credit Card</strong>, and <strong>Phone Number</strong>. For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td></tr><tr><td><div><div><p>Custom PII Patterns</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Array of custom regex patterns to detect additional sensitive values. Define a name and regex pattern for each array entry. For example, use <code>name: AWS Access Key</code> and <code>pattern: AKIA[0-9A-Z]{16}</code> to detect AWS access keys.</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Action to take when PII is detected in a request. Supported values are <strong>Reject</strong>, <strong>Log</strong>, and <strong>Log and mask</strong>. Default is <strong>Log</strong>.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The policy scans OpenAI and Anthropic format JSON body traffic. It recursively inspects all string
values in the JSON body, including all conversation messages. The policy only inspects requests
whose method is `POST`.

For request processing:

- If **Action** is **Reject**, the policy blocks the request and returns HTTP `403`.

- If **Action** is **Log** or **Log and mask**, the policy forwards the request and logs findings.

For response processing:

- The policy scans JSON responses and logs findings.

- Responses are not blocked, regardless of action.

## PII Types

When you configure the LLM PII Detection policy, choose which types of PII to detect.

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code>.</p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs), including formats with various delimiters such as <code>123-45-6789</code>, <code>123 45 6789</code>, <code>123.45.6789</code>, <code>123,45,6789</code>, <code>123/45/6789</code>, <code>123\45\6789</code>, or <code>123456789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers for Visa, MasterCard, American Express, and Discover, with or without separators. Examples: <code>4111-1111-1111-1111</code>, <code>4111 1111 1111 1111</code>, <code>4111111111111111</code>, <code>4111.1111.1111.1111</code>, <code>5500-0000-0000-0004</code>, <code>3782-822463-10005</code>, <code>6011-0000-0000-0004</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>Phone numbers in common domestic and international formats based on ITU E.164 country codes. Examples include US numbers like <code>(555) 123-4567</code>, <code>555-123-4567</code>, <code>+1-555-123-4567</code>, and international numbers like <code>+91 98765 43210</code>, <code>+44 20 7946 0958</code>, <code>+49 30 12345678</code>.</p></div></div></td></tr></tbody></table>

## Response on Reject

When the policy blocks a request, it returns a `403` response with this structure:

```json
{
  "error": {
    "message": "Request contains PII data: <findings>",
    "type": "pii_detected"
  }
}
```

## Example Request and Logging

This example shows a request containing PII and the corresponding log output for different action
configurations.

```http
POST /v1/chat/completions HTTP/1.1
Content-Type: application/json

{
  "model": "gemini/gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "Look up the account for SSN 123-45-6789 and email john@example.com"},
    {"role": "user", "content": "Look up the account for credit card 4123 8171 5881 9171"},
    {"role": "user", "content": "hello"}
  ]
}
```

- Log

- Log and Mask

When the action is set to **Log**, the policy logs detected PII with the actual values:

```json
[accessLog]  PII detected in LLM request (log only): [
  {
    "pii_type": "SSN",
    "value": "123-45-6789",
    "start": 28,
    "end": 39
  },
  {
    "pii_type": "Email",
    "value": "john@example.com",
    "start": 50,
    "end": 66
  },
  {
    "pii_type": "CreditCard",
    "value": "4123 8171 5881 9171",
    "start": 31,
    "end": 50
  }
]
```

When the action is set to **Log and mask**, the policy logs detected PII with masked values:

```json
[accessLog]  PII detected in LLM request (log only): [
  {
    "pii_type": "SSN",
    "masked_value": "***-**-*789",
    "start": 28,
    "end": 39
  },
  {
    "pii_type": "Email",
    "masked_value": "****@example.com",
    "start": 50,
    "end": 66
  },
  {
    "pii_type": "CreditCard",
    "masked_value": "*************171",
    "start": 31,
    "end": 50
  }
]
```

### Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern:

```http
POST /v1/chat/completions HTTP/1.1
Content-Type: application/json

{
  "model": "gemini/gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment"}
  ]
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy
logs:

```json
[accessLog] PII detected in LLM request (log only): [
  {
    "pii_type": "AWS Access Key",
    "masked_value": "********************",
    "start": 19,
    "end": 39
  }
]
```

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Regex Prompt Guard](https://docs.mulesoft.com/gateway/1.13/policies-included-regex-prompt-guard)

- [LLM Token Based Rate Limit](https://docs.mulesoft.com/gateway/1.13/policies-included-llm-token-rate-limit)

<!-- document id=742233faaa8d597a4e9c6c402c688a6cdd86464de776139d8d3990f866d26730 url=/mulesoft/current/en-us/gateway/latest/policies-included-llm-pii-detection.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, pii, personally identifiable information
---

# LLM PII Detection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>LLM PII Detection Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Detects personally identifiable information (PII) in OpenAI and Anthropic format LLM requests and responses</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-pii-detection-release-notes">LLM PII Detection</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden</p></td></tr></tbody></table>

## Summary

The LLM Personally Identifiable Information (PII) Detection policy scans OpenAI and Anthropic format
Model Proxy traffic for PII.

The policy inspects incoming request bodies and outgoing response bodies for PII.

When PII is detected, the policy reports a policy violation. For request traffic, you configure
whether to reject the request, log findings, or log masked findings. Response traffic is never
blocked.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The LLM PII Detection policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>PII Types</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Array of built-in PII types to detect. Supported values are <strong>Email</strong>, <strong>US SSN</strong>, <strong>Credit Card</strong>, and <strong>Phone Number</strong>. For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td></tr><tr><td><div><div><p>Custom PII Patterns</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Array of custom regex patterns to detect additional sensitive values. Define a name and regex pattern for each array entry. For example, use <code>name: AWS Access Key</code> and <code>pattern: AKIA[0-9A-Z]{16}</code> to detect AWS access keys.</p></div></div></td></tr><tr><td><div><div><p>Action</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Action to take when PII is detected in a request. Supported values are <strong>Reject</strong>, <strong>Log</strong>, and <strong>Log and mask</strong>. Default is <strong>Log</strong>.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The policy scans OpenAI and Anthropic format JSON body traffic. It recursively inspects all string
values in the JSON body, including all conversation messages. The policy only inspects requests
whose method is `POST`.

For request processing:

- If **Action** is **Reject**, the policy blocks the request and returns HTTP `403`.

- If **Action** is **Log** or **Log and mask**, the policy forwards the request and logs findings.

For response processing:

- The policy scans JSON responses and logs findings.

- Responses are not blocked, regardless of action.

## PII Types

When you configure the LLM PII Detection policy, choose which types of PII to detect.

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code>.</p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs), including formats with various delimiters such as <code>123-45-6789</code>, <code>123 45 6789</code>, <code>123.45.6789</code>, <code>123,45,6789</code>, <code>123/45/6789</code>, <code>123\45\6789</code>, or <code>123456789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers for Visa, MasterCard, American Express, and Discover, with or without separators. Examples: <code>4111-1111-1111-1111</code>, <code>4111 1111 1111 1111</code>, <code>4111111111111111</code>, <code>4111.1111.1111.1111</code>, <code>5500-0000-0000-0004</code>, <code>3782-822463-10005</code>, <code>6011-0000-0000-0004</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>Phone numbers in common domestic and international formats based on ITU E.164 country codes. Examples include US numbers like <code>(555) 123-4567</code>, <code>555-123-4567</code>, <code>+1-555-123-4567</code>, and international numbers like <code>+91 98765 43210</code>, <code>+44 20 7946 0958</code>, <code>+49 30 12345678</code>.</p></div></div></td></tr></tbody></table>

## Response on Reject

When the policy blocks a request, it returns a `403` response with this structure:

```json
{
  "error": {
    "message": "Request contains PII data: <findings>",
    "type": "pii_detected"
  }
}
```

## Example Request and Logging

This example shows a request containing PII and the corresponding log output for different action
configurations.

```http
POST /v1/chat/completions HTTP/1.1
Content-Type: application/json

{
  "model": "gemini/gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "Look up the account for SSN 123-45-6789 and email john@example.com"},
    {"role": "user", "content": "Look up the account for credit card 4123 8171 5881 9171"},
    {"role": "user", "content": "hello"}
  ]
}
```

- Log

- Log and Mask

When the action is set to **Log**, the policy logs detected PII with the actual values:

```json
[accessLog]  PII detected in LLM request (log only): [
  {
    "pii_type": "SSN",
    "value": "123-45-6789",
    "start": 28,
    "end": 39
  },
  {
    "pii_type": "Email",
    "value": "john@example.com",
    "start": 50,
    "end": 66
  },
  {
    "pii_type": "CreditCard",
    "value": "4123 8171 5881 9171",
    "start": 31,
    "end": 50
  }
]
```

When the action is set to **Log and mask**, the policy logs detected PII with masked values:

```json
[accessLog]  PII detected in LLM request (log only): [
  {
    "pii_type": "SSN",
    "masked_value": "***-**-*789",
    "start": 28,
    "end": 39
  },
  {
    "pii_type": "Email",
    "masked_value": "****@example.com",
    "start": 50,
    "end": 66
  },
  {
    "pii_type": "CreditCard",
    "masked_value": "*************171",
    "start": 31,
    "end": 50
  }
]
```

### Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern:

```http
POST /v1/chat/completions HTTP/1.1
Content-Type: application/json

{
  "model": "gemini/gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "Use this AWS key: AKIAIOSFODNN7EXAMPLE for deployment"}
  ]
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy
logs:

```json
[accessLog] PII detected in LLM request (log only): [
  {
    "pii_type": "AWS Access Key",
    "masked_value": "********************",
    "start": 19,
    "end": 39
  }
]
```

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Regex Prompt Guard](https://docs.mulesoft.com/gateway/latest/policies-included-regex-prompt-guard)

- [LLM Token Based Rate Limit](https://docs.mulesoft.com/gateway/latest/policies-included-llm-token-rate-limit)

<!-- document id=48b533efcf4ad8cb76e5e41f2c32c2b2472fe12b6e10af8208d433abd2afd385 url=/mulesoft/current/en-us/gateway/1.12/policies-included-llm-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, rate limiting, token, llm, openai
---

# LLM Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>LLM Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits Model Proxy usage based on token consumption</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

## Summary

The LLM Token Based Rate Limit policy enforces rate limiting on Model Proxy requests based on the
number of tokens consumed providing control over API usage based on actual token consumption
reported by the upstream LLM provider.

It counts request, response, and reasoning token (if applicable). When the token limit is exceeded,
the policy blocks the call and returns a `429` status code.

The policy supports both streaming and non-streaming responses.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The LLM Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed within the specified time period. Must be a positive integer of one or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit window. Minimum time period is 1000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. For example:</p></div><div><ul><li><p><code>#[attributes.headers['client_id']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per user</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The LLM Token Based Rate Limit policy monitors token consumption in the current window, allowing
requests to reach the backend only if the available token quota is greater than zero.

The policy uses a fixed-window rate limiting algorithm. The window starts after it receives the
first request. When the quota is exhausted, requests are rejected with a `429` status code until the
time window resets.

The `keySelector` parameter enables you to create independent rate limit counters for different
groups of requests. Each unique value resolved by the DataWeave expression has its own token quota
and time window. For example, if you configure `keySelector: "#[attributes.headers['client_id']]"`
with a limit of 1000 tokens per 60 seconds, each client has its own 1000-token quota in a 60-second
window.

### Response Headers

When a request is processed, the policy adds the following headers to the response:

- `x-token-limit`: The maximum number of tokens allowed per window

- `x-token-remaining`: The number of tokens remaining in the current window

- `x-token-reset`: The remaining time, in milliseconds, until a new window starts

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

- [Viewing Token Usage and Model Proxy Metrics](https://docs.mulesoft.com/general/model-proxy-token-reports) - Token
  usage reports and limiting usage

- [A2A Token Based Rate Limit](https://docs.mulesoft.com/gateway/1.12/policies-included-a2a-token-rate-limit) - Token-based rate limiting
  for A2A agent traffic

<!-- document id=f0155bffc41434f645b57cfef8269a7eb331dd316305960b73e1841eba7eab5c url=/mulesoft/current/en-us/gateway/1.13/policies-included-llm-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, rate limiting, token, llm, openai
---

# LLM Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>LLM Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits Model Proxy usage based on token consumption</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-token-rate-limit-release-notes">LLM Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

## Summary

The LLM Token Based Rate Limit policy enforces rate limiting on Model Proxy requests based on the
number of tokens consumed providing control over API usage based on actual token consumption
reported by the upstream LLM provider.

It counts request, response, and reasoning token (if applicable). When the token limit is exceeded,
the policy blocks the call and returns a `429` status code.

The policy supports both streaming and non-streaming responses.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The LLM Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed within the specified time period. Must be a positive integer of one or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit window. Minimum time period is 1000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. For example:</p></div><div><ul><li><p><code>#[attributes.headers['client_id']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per user</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The LLM Token Based Rate Limit policy monitors token consumption in the current window, allowing
requests to reach the backend only if the available token quota is greater than zero.

The policy uses a fixed-window rate limiting algorithm. The window starts after it receives the
first request. When the quota is exhausted, requests are rejected with a `429` status code until the
time window resets.

The `keySelector` parameter enables you to create independent rate limit counters for different
groups of requests. Each unique value resolved by the DataWeave expression has its own token quota
and time window. For example, if you configure `keySelector: "#[attributes.headers['client_id']]"`
with a limit of 1000 tokens per 60 seconds, each client has its own 1000-token quota in a 60-second
window.

### Response Headers

When a request is processed, the policy adds the following headers to the response:

- `x-token-limit`: The maximum number of tokens allowed per window

- `x-token-remaining`: The number of tokens remaining in the current window

- `x-token-reset`: The remaining time, in milliseconds, until a new window starts

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

- [Viewing Token Usage and Model Proxy Metrics](https://docs.mulesoft.com/general/model-proxy-token-reports) - Token
  usage reports and limiting usage

- [A2A Token Based Rate Limit](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-token-rate-limit) - Token-based rate limiting
  for A2A agent traffic

<!-- document id=c40b4fc2bd38e4083ab18fb7915ee921a94d51c48e03ee22a89688a025aaf913 url=/mulesoft/current/en-us/gateway/latest/policies-included-llm-token-rate-limit.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, rate limiting, token, llm, openai
---

# LLM Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>LLM Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits Model Proxy usage based on token consumption</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-token-rate-limit-release-notes">LLM Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

## Summary

The LLM Token Based Rate Limit policy enforces rate limiting on Model Proxy requests based on the
number of tokens consumed providing control over API usage based on actual token consumption
reported by the upstream LLM provider.

It counts request, response, and reasoning token (if applicable). When the token limit is exceeded,
the policy blocks the call and returns a `429` status code.

The policy supports both streaming and non-streaming responses.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The LLM Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed within the specified time period. Must be a positive integer of one or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit window. Minimum time period is 1000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. For example:</p></div><div><ul><li><p><code>#[attributes.headers['client_id']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per user</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The LLM Token Based Rate Limit policy monitors token consumption in the current window, allowing
requests to reach the backend only if the available token quota is greater than zero.

The policy uses a fixed-window rate limiting algorithm. The window starts after it receives the
first request. When the quota is exhausted, requests are rejected with a `429` status code until the
time window resets.

The `keySelector` parameter enables you to create independent rate limit counters for different
groups of requests. Each unique value resolved by the DataWeave expression has its own token quota
and time window. For example, if you configure `keySelector: "#[attributes.headers['client_id']]"`
with a limit of 1000 tokens per 60 seconds, each client has its own 1000-token quota in a 60-second
window.

### Response Headers

When a request is processed, the policy adds the following headers to the response:

- `x-token-limit`: The maximum number of tokens allowed per window

- `x-token-remaining`: The number of tokens remaining in the current window

- `x-token-reset`: The remaining time, in milliseconds, until a new window starts

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

- [Viewing Token Usage and Model Proxy Metrics](https://docs.mulesoft.com/general/model-proxy-token-reports) - Token
  usage reports and limiting usage

- [A2A Token Based Rate Limit](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-token-rate-limit) - Token-based rate limiting
  for A2A agent traffic

<!-- document id=c9e820abe70e374bd8466c6e5576a46aea38ead8d3f8bd4192ed1f718f639d30 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-managed-dr-ha.md -->

---
product: Omni Gateway
version: 1.12
---

# Managed Flex Gateway High Availability and Disaster Recovery Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

CloudHub 2.0 and Runtime Fabric manage Managed Flex Gateway replica deployments and control the
gateway’s high availability and disaster recovery. To learn about how these deployment targets
handle disaster recovery and high availability not specific to Flex Gateway, familiarize yourself
with [CloudHub 2.0 High Availability and Disaster Recovery](https://docs.mulesoft.com/cloudhub-2/ch2-ha-dr).

High availability and disaster recovery is handled the same across gateway sizes.

This diagram shows how multiple Managed Flex Gateway replicas are deployed.

![External traffic flows through CloudHub 2.0 Ingress to a Kubernetes service that distributes requests across multiple Managed Flex Gateway replicas](/mulesoft/current/en-us/gateway/1.12/_images/managed-high-availability.png)

External traffic entering through private space ingress is distributed across a kubernetes service
of Managed Flex Gateway instances. Replicas share the gateway configuration and data that must
persist in a Kubernetes resource. Replicas share HTTP caching and distributed rate limiting data
directly with each other.

> [!NOTE] The diagram shows CloudHub 2.0 ingress. For Runtime Fabric, you must configure your own
> ingress. Your ingress must terminate TLS before forwarding the request to the Managed Flex
> Gateway.

## Managed Flex Gateway High Availability

The private space manages Managed Flex Gateway high availability by ensuring:

- At least two Flex replicas are always available and distributed across different availability
  zones in the private space. Traffic is distributed to replicas and zones evenly using a round
  robin traffic distribution.

  - If a replica fails, a new replica is spawned. While respawning the replica, the outstanding
    replicas receive a temporary spike in traffic until the new replica can accept traffic. These
    short spikes in traffic are visible in monitoring as a temporary spike in CPU usage.

  - Overloaded gateways don’t abruptly stop incoming traffic processing as a result of overload.
    However, overloaded gateways show gradual degradation of response time for requests until CPU
    subsides.

- Large and extra large Managed Flex Gateways have more capacity allocated per replica and autoscale
  up to three replicas across three availability zones depending on CPU usage.

## Managed Flex Gateway Configuration Storage

Managed Flex gateway stores API configurations locally in the private space kubernetes service.
Locally stored configurations enable the gateway to start faster than an equivalently configured
Self Managed Flex Gateway (that needs to download the configuration from Anypoint upon start).
Locally stored configurations provide a layer of resiliency in the unlikely event that the Anypoint
control plane isn’t reachable during Managed Gateway startup.

Managed Flex Gateway does not store contracts locally. Upon starting, Managed Flex Gateway downloads
contracts from Anypoint Platform. If an API uses contracts, for example if the client ID enforcement
policy is applied, the gateway downloads the contracts before accepting traffic.

<!-- document id=fe393f98002cdff72a502f62bc75f6f72698b4a7b00633d4dcc5f15c5c8ada5d url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-managed-dr-ha.md -->

---
product: Omni Gateway
version: 1.13
---

# Managed Omni Gateway High Availability and Disaster Recovery Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

CloudHub 2.0 and Runtime Fabric manage Managed Omni Gateway replica deployments and control the
gateway’s high availability and disaster recovery. To learn about how these deployment targets
handle disaster recovery and high availability not specific to Omni Gateway, familiarize yourself
with [CloudHub 2.0 High Availability and Disaster Recovery](https://docs.mulesoft.com/cloudhub-2/ch2-ha-dr).

High availability and disaster recovery are handled the same across all gateway sizes. Autoscaling
behavior differs by size. All sizes run at least two replicas across availability zones, but only
large and extra large gateways autoscale to add replicas based on CPU usage.

This diagram shows how multiple Managed Omni Gateway replicas are deployed.

![External traffic flows through CloudHub 2.0 Ingress to a Kubernetes service that distributes requests across multiple Managed Omni Gateway replicas](/mulesoft/current/en-us/gateway/1.13/_images/managed-high-availability.png)

External traffic entering through private space ingress is distributed across a kubernetes service
of Managed Omni Gateway instances. Replicas share the gateway configuration and data that must
persist in a Kubernetes resource. Replicas share HTTP caching and distributed rate limiting data
directly with each other.

> [!NOTE] The diagram shows CloudHub 2.0 ingress. For Runtime Fabric, you must configure your own
> ingress. Your ingress must terminate TLS before forwarding the request to the Managed Omni
> Gateway.

## Managed Omni Gateway High Availability

The private space manages Managed Omni Gateway high availability by ensuring:

- At least two Omni replicas are always available and distributed across different availability
  zones in the private space. Traffic is distributed to replicas and zones evenly using a round
  robin traffic distribution.

  - If a replica fails, a new replica is spawned. While respawning the replica, the outstanding
    replicas receive a temporary spike in traffic until the new replica can accept traffic. These
    short spikes in traffic are visible in monitoring as a temporary spike in CPU usage.

  - Overloaded gateways don’t abruptly stop incoming traffic processing as a result of overload.
    However, overloaded gateways show gradual degradation of response time for requests until CPU
    subsides.

- Large and extra large Managed Omni Gateways have more capacity allocated per replica and autoscale
  by adding replicas across availability zones depending on CPU usage.

## Managed Omni Gateway Configuration Storage

Managed Omni Gateway stores API configurations locally in the private space kubernetes service.
Locally stored configurations enable the gateway to start faster than an equivalently configured
Self Managed Omni Gateway (that needs to download the configuration from Anypoint upon start).
Locally stored configurations provide a layer of resiliency in the unlikely event that the Anypoint
control plane isn’t reachable during Managed Gateway startup.

Managed Omni Gateway does not store contracts locally. Upon starting, Managed Omni Gateway downloads
contracts from Anypoint Platform. If an API uses contracts, for example if the client ID enforcement
policy is applied, the gateway downloads the contracts before accepting traffic.

<!-- document id=562d294c2390d44a01f372d3b2b93831cb2e6602f4f31cd974ad0f0ddc5b3dd4 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-managed-dr-ha.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Managed Omni Gateway High Availability and Disaster Recovery Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

CloudHub 2.0 and Runtime Fabric manage Managed Omni Gateway replica deployments and control the
gateway’s high availability and disaster recovery. To learn about how these deployment targets
handle disaster recovery and high availability not specific to Omni Gateway, familiarize yourself
with [CloudHub 2.0 High Availability and Disaster Recovery](https://docs.mulesoft.com/cloudhub-2/ch2-ha-dr).

High availability and disaster recovery are handled the same across all gateway sizes. Autoscaling
behavior differs by size. All sizes run at least two replicas across availability zones, but only
large and extra large gateways autoscale to add replicas based on CPU usage.

This diagram shows how multiple Managed Omni Gateway replicas are deployed.

![External traffic flows through CloudHub 2.0 Ingress to a Kubernetes service that distributes requests across multiple Managed Omni Gateway replicas](/mulesoft/current/en-us/gateway/latest/_images/managed-high-availability.png)

External traffic entering through private space ingress is distributed across a kubernetes service
of Managed Omni Gateway instances. Replicas share the gateway configuration and data that must
persist in a Kubernetes resource. Replicas share HTTP caching and distributed rate limiting data
directly with each other.

> [!NOTE] The diagram shows CloudHub 2.0 ingress. For Runtime Fabric, you must configure your own
> ingress. Your ingress must terminate TLS before forwarding the request to the Managed Omni
> Gateway.

## Managed Omni Gateway High Availability

The private space manages Managed Omni Gateway high availability by ensuring:

- At least two Omni replicas are always available and distributed across different availability
  zones in the private space. Traffic is distributed to replicas and zones evenly using a round
  robin traffic distribution.

  - If a replica fails, a new replica is spawned. While respawning the replica, the outstanding
    replicas receive a temporary spike in traffic until the new replica can accept traffic. These
    short spikes in traffic are visible in monitoring as a temporary spike in CPU usage.

  - Overloaded gateways don’t abruptly stop incoming traffic processing as a result of overload.
    However, overloaded gateways show gradual degradation of response time for requests until CPU
    subsides.

- Large and extra large Managed Omni Gateways have more capacity allocated per replica and autoscale
  by adding replicas across availability zones depending on CPU usage.

## Managed Omni Gateway Configuration Storage

Managed Omni Gateway stores API configurations locally in the private space kubernetes service.
Locally stored configurations enable the gateway to start faster than an equivalently configured
Self Managed Omni Gateway (that needs to download the configuration from Anypoint upon start).
Locally stored configurations provide a layer of resiliency in the unlikely event that the Anypoint
control plane isn’t reachable during Managed Gateway startup.

Managed Omni Gateway does not store contracts locally. Upon starting, Managed Omni Gateway downloads
contracts from Anypoint Platform. If an API uses contracts, for example if the client ID enforcement
policy is applied, the gateway downloads the contracts before accepting traffic.

<!-- document id=e24a73cca7b3345b600e60447dba7427cfe74648a3a251a2e206dbb4727895ae url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-k8-management.md -->

---
product: Omni Gateway
version: 1.12
---

# Managing Kubernetes Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings) -
  Change requirements for a Pod that contains Flex Gateway.

- [Autoscale and Add Flex Gateway Replicas to a Namespace](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-high-availability) - Set
  a fixed replica count or autoscale to provide additional replicas.

- [Configure Node Selection for Flex Gateway Deployments on Kubernetes (Node Affinity)](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-node-affinity-config) -
  Host Flex Gateway on a specialized node that meets specific requirements.

- [Provide a Domain Name for an Application on Your Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-external-dns) -
  Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain
  name.

- [Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class) -
  Configure Flex Gateway as an `IngressClass` to manage `Ingress` resources.

- [Integrating Flex Gateway with Istio Service Mesh](https://docs.mulesoft.com/gateway/1.12/flex-gateway-istio) - Integrate Flex Gateway
  into your Istio Service Mesh to leverage Flex Gateway policies, logging, and metrics from the
  Anypoint Platform control plane.

## See Also

- [Upgrade in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-upgrade#kubernetes)

- [Uninstall from a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-uninstall#kubernetes)

- [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-getting-started)

<!-- document id=67da879694a30dae6a1361f791c495329b32e88f5ea82134d66c2bcbcc9f3595 url=/mulesoft/current/en-us/gateway/1.13/gateway-k8-management.md -->

---
product: Omni Gateway
version: 1.13
---

# Managing Kubernetes Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings) -
  Change requirements for a Pod that contains Omni Gateway.

- [Autoscale and Add Omni Gateway Replicas to a Namespace](https://docs.mulesoft.com/gateway/1.13/gateway-k8-high-availability) - Set a
  fixed replica count or autoscale to provide additional replicas.

- [Configure Node Selection for Omni Gateway Deployments on Kubernetes (Node Affinity)](https://docs.mulesoft.com/gateway/1.13/gateway-k8-node-affinity-config) -
  Host Omni Gateway on a specialized node that meets specific requirements.

- [Provide a Domain Name for an Application on Your Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-k8-external-dns) -
  Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain
  name.

- [Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class) -
  Configure Omni Gateway as an `IngressClass` to manage `Ingress` resources.

- [Integrating Omni Gateway with Istio Service Mesh](https://docs.mulesoft.com/gateway/1.13/gateway-istio) - Integrate Omni Gateway into
  your Istio Service Mesh to leverage Omni Gateway policies, logging, and metrics from the Anypoint
  Platform control plane.

## See Also

- [Upgrade in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-upgrade#kubernetes)

- [Uninstall from a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-uninstall#kubernetes)

- [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-k8-getting-started)

<!-- document id=a88bc38a4e865182ed21930a6ab725f322308ab58f55431638a945e533cc1895 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-k8-management.md -->

---
product: Omni Gateway
version: 1.9
---

# Managing Kubernetes Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings) -
  Change requirements for a Pod that contains Flex Gateway.

- [Autoscale and Add Flex Gateway Replicas to a Namespace](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-high-availability) - Set
  a fixed replica count or autoscale to provide additional replicas.

- [Configure Node Selection for Flex Gateway Deployments on Kubernetes (Node Affinity)](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-node-affinity-config) -
  Host Flex Gateway on a specialized node that meets specific requirements.

- [Provide a Domain Name for an Application on Your Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-external-dns) -
  Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain
  name.

- [Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class) -
  Configure Flex Gateway as an `IngressClass` to manage `Ingress` resources.

- [Integrating Flex Gateway with Istio Service Mesh](https://docs.mulesoft.com/gateway/1.9/flex-gateway-istio) - Integrate Flex Gateway
  into your Istio Service Mesh to leverage Flex Gateway policies, logging, and metrics from the
  Anypoint Platform control plane.

## See Also

- [Upgrade in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-upgrade#kubernetes)

- [Uninstall from a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-uninstall#kubernetes)

- [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-getting-started)

<!-- document id=98d11af13ea36d58462910ac3516896b51fd39ed0ee3a1b6cd6999ee25ad9979 url=/mulesoft/current/en-us/gateway/latest/gateway-k8-management.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Managing Kubernetes Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

- [Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings) -
  Change requirements for a Pod that contains Omni Gateway.

- [Autoscale and Add Omni Gateway Replicas to a Namespace](https://docs.mulesoft.com/gateway/latest/gateway-k8-high-availability) - Set a
  fixed replica count or autoscale to provide additional replicas.

- [Configure Node Selection for Omni Gateway Deployments on Kubernetes (Node Affinity)](https://docs.mulesoft.com/gateway/latest/gateway-k8-node-affinity-config) -
  Host Omni Gateway on a specialized node that meets specific requirements.

- [Provide a Domain Name for an Application on Your Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-k8-external-dns) -
  Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain
  name.

- [Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class) -
  Configure Omni Gateway as an `IngressClass` to manage `Ingress` resources.

- [Integrating Omni Gateway with Istio Service Mesh](https://docs.mulesoft.com/gateway/latest/gateway-istio) - Integrate Omni Gateway into
  your Istio Service Mesh to leverage Omni Gateway policies, logging, and metrics from the Anypoint
  Platform control plane.

## See Also

- [Upgrade in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-upgrade#kubernetes)

- [Uninstall from a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-uninstall#kubernetes)

- [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-k8-getting-started)

<!-- document id=197542dfe998453775460131f1c267a65b141c04639c7d438b717e0e96a62178 url=/mulesoft/current/en-us/gateway/1.12/policies-included-mcp-attribute-access-control.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Attribute-Based Access Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Attribute-Based Access Control</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Attribute-Based Access Control policy controls access to server tools, resources, and
prompts based on user information such as Tiers, IP, Headers, or Claims. Use the
[Cedar policy language](https://docs.cedarpolicy.com/) to define access rules.

This policy requires that another authentication policy be applied before the MCP Attribute-Based
Access Control policy. For detailed guidance, see [Writing Cedar Rules](#writing-cedar-rules).

## Configuring Policy Parameters

### Flex Gateway Local Mode

The MCP Attribute-Based Access Control policy is not supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>Rules to control access to tools, resources, and prompts written in the <a href="https://docs.cedarpolicy.com/">Cedar policy language</a>.</p></div></div></td></tr><tr><td><div><div><p>Cedar Expression</p></div></div></td><td><div><div><p>Cedar expression defining the access rule. For example: <code>permit(principal,action == Action::"tools/call</code> or <code>resource == Tool::"calculator");</code>. To learn more about the Cedar bindings provided by the requests, see <a href="#writing-cedar-rules">Writing Cedar Rules</a>.</p></div></div></td></tr><tr><td><div><div><p>Authentication Type</p></div></div></td><td><div><div><p>Type of authentication used by the authentication policy applied before this policy.</p></div></div></td></tr></tbody></table>

## Writing Cedar Rules

You must apply either an included authentication policy or a custom authentication policy before the
MCP Attribute-Based Access Control policy.

### Included Authentication Policies

The authentication policy you apply affects the available Cedar `principal` bindings:

- Multiple policies can validate Client ID:

  - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-client-id-enforcement)

  - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting-sla)

  - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-oauth-token-introspection) (If Client
    ID enforcement is configured)

  - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-openid-token-enforcement)
    (If Client ID enforcement is configured)

  - [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-jwt-validation) (If Client ID enforcement is
    configured)

    Policies validating Client ID provide these Cedar bindings:

  - `principal.client_name`: Name of the contract’s client application

  - `principal.principal`: ID of the contract’s client application

  - `principal.properties.slaId`: SLA ID assigned to the contract

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-jwt-validation):

  - `principal.properties.claims.<claimName>`: All claims provided by the JWT

- Multiple policies validate basic authentication credentials:

  - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-simple)

  - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-ldap)

    Policies validating basic authentication credentials provide these Cedar bindings:

  - `principal.principal`: Username passed as basic auth user

### Custom Authentication Policies

For custom authentication policies, the custom policy must authenticate by using the
`Authentication` injectable. To configure the `Authentication` injectable, see
[Accessing Request Authentication Information](https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features-authentication).

For the Rust `AuthenticationData` struct:

```rust
pub struct AuthenticationData {
    pub principal: Option<String>,
    pub client_id: Option<String>,
    pub client_name: Option<String>,
    pub properties: Value,
}
```

The `AuthenticationData` parameters map to these Cedar bindings:

- `principal`: `principal.principal`

- `client_name`: `principal.client_name`

- `properties`: `principal.properties.*`

## See Also

- [Configuring MCP Access Control Policies](https://docs.mulesoft.com/gateway/1.12/policies-mcp-access-control-together)

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-global-access)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-tool-mapping)

<!-- document id=d111f2bf9fbd2819f8ddd061b85b6767310fd82fdef0e0558a3df84df9b85006 url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-attribute-access-control.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Attribute-Based Access Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Attribute-Based Access Control</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-attribute-access-control-release-notes">MCP Attribute-Based Access Control</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Attribute-Based Access Control policy controls access to server tools, resources, and
prompts based on user information such as Tiers, IP, Headers, or Claims. Use the
[Cedar policy language](https://docs.cedarpolicy.com/) to define access rules.

This policy requires that another authentication policy be applied before the MCP Attribute-Based
Access Control policy. For detailed guidance, see [Writing Cedar Rules](#writing-cedar-rules).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Attribute-Based Access Control policy is not supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>Rules to control access to tools, resources, and prompts written in the <a href="https://docs.cedarpolicy.com/">Cedar policy language</a>.</p></div></div></td></tr><tr><td><div><div><p>Cedar Expression</p></div></div></td><td><div><div><p>Cedar expression defining the access rule. For example: <code>permit(principal,action == Action::"tools/call</code> or <code>resource == Tool::"calculator");</code>. To learn more about the Cedar bindings provided by the requests, see <a href="#writing-cedar-rules">Writing Cedar Rules</a>.</p></div></div></td></tr><tr><td><div><div><p>Authentication Type</p></div></div></td><td><div><div><p>Type of authentication used by the authentication policy applied before this policy.</p></div></div></td></tr></tbody></table>

## Writing Cedar Rules

You must apply either an included authentication policy or a custom authentication policy before the
MCP Attribute-Based Access Control policy.

### Included Authentication Policies

The authentication policy you apply affects the available Cedar `principal` bindings:

- Multiple policies can validate Client ID:

  - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-client-id-enforcement)

  - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting-sla)

  - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-oauth-token-introspection) (If Client
    ID enforcement is configured)

  - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-openid-token-enforcement)
    (If Client ID enforcement is configured)

  - [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-jwt-validation) (If Client ID enforcement is
    configured)

    Policies validating Client ID provide these Cedar bindings:

  - `principal.client_name`: Name of the contract’s client application

  - `principal.principal`: ID of the contract’s client application

  - `principal.properties.slaId`: SLA ID assigned to the contract

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-jwt-validation):

  - `principal.properties.claims.<claimName>`: All claims provided by the JWT

- Multiple policies validate basic authentication credentials:

  - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-simple)

  - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-ldap)

    Policies validating basic authentication credentials provide these Cedar bindings:

  - `principal.principal`: Username passed as basic auth user

### Custom Authentication Policies

For custom authentication policies, the custom policy must authenticate by using the
`Authentication` injectable. To configure the `Authentication` injectable, see
[Accessing Request Authentication Information](https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features-authentication).

For the Rust `AuthenticationData` struct:

```rust
pub struct AuthenticationData {
    pub principal: Option<String>,
    pub client_id: Option<String>,
    pub client_name: Option<String>,
    pub properties: Value,
}
```

The `AuthenticationData` parameters map to these Cedar bindings:

- `principal`: `principal.principal`

- `client_name`: `principal.client_name`

- `properties`: `principal.properties.*`

## See Also

- [Configuring MCP Access Control Policies](https://docs.mulesoft.com/gateway/1.13/policies-mcp-access-control-together)

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-global-access)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping)

<!-- document id=cc0dedc1da76718aa6cbdc027f15091db00707fc360111a8b1f9a338f7c171ae url=/mulesoft/current/en-us/gateway/1.9/policies-included-mcp-attribute-access-control.md -->

---
product: Omni Gateway
version: 1.9
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Attribute-Based Access Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Attribute-Based Access Control</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr></tbody></table>

## Summary

The MCP Attribute-Based Access Control policy controls access to server tools, resources, and
prompts based on user information such as Tiers, IP, Headers, or Claims. Use the
[Cedar policy language](https://docs.cedarpolicy.com/) to define access rules.

This policy requires that another authentication policy be applied before the MCP Attribute-Based
Access Control policy. For detailed guidance, see [Writing Cedar Rules](#writing-cedar-rules).

## Configuring Policy Parameters

### Flex Gateway Local Mode

The MCP Attribute-Based Access Control policy is not supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>Rules to control access to tools, resources, and prompts written in the <a href="https://docs.cedarpolicy.com/">Cedar policy language</a>.</p></div></div></td></tr><tr><td><div><div><p>Cedar Expression</p></div></div></td><td><div><div><p>Cedar expression defining the access rule. For example: <code>permit(principal,action == Action::"tools/call</code> or <code>resource == Tool::"calculator");</code>. To learn more about the Cedar bindings provided by the requests, see <a href="#writing-cedar-rules">Writing Cedar Rules</a>.</p></div></div></td></tr><tr><td><div><div><p>Authentication Type</p></div></div></td><td><div><div><p>Type of authentication used by the authentication policy applied before this policy.</p></div></div></td></tr></tbody></table>

## Writing Cedar Rules

You must apply either an included authentication policy or a custom authentication policy before the
MCP Attribute-Based Access Control policy.

### Included Authentication Policies

The authentication policy you apply affects the available Cedar `principal` bindings:

- Multiple policies can validate Client ID:

  - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-client-id-enforcement)

  - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting-sla)

  - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-oauth-token-introspection) (If Client
    ID enforcement is configured)

  - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-openid-token-enforcement)
    (If Client ID enforcement is configured)

  - [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-jwt-validation) (If Client ID enforcement is
    configured)

    Policies validating Client ID provide these Cedar bindings:

  - `principal.client_name`: Name of the contract’s client application

  - `principal.principal`: ID of the contract’s client application

  - `principal.properties.slaId`: SLA ID assigned to the contract

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-jwt-validation):

  - `principal.properties.claims.<claimName>`: All claims provided by the JWT

- Multiple policies validate basic authentication credentials:

  - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-simple)

  - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-ldap)

    Policies validating basic authentication credentials provide these Cedar bindings:

  - `principal.principal`: Username passed as basic auth user

### Custom Authentication Policies

For custom authentication policies, the custom policy must authenticate by using the
`Authentication` injectable. To configure the `Authentication` injectable, see
[Accessing Request Authentication Information](https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features-authentication).

For the Rust `AuthenticationData` struct:

```rust
pub struct AuthenticationData {
    pub principal: Option<String>,
    pub client_id: Option<String>,
    pub client_name: Option<String>,
    pub properties: Value,
}
```

The `AuthenticationData` parameters map to these Cedar bindings:

- `principal`: `principal.principal`

- `client_name`: `principal.client_name`

- `properties`: `principal.properties.*`

<!-- document id=762209d93861e1276d9a91da7084e9230db4ff39ef0de8a034c49d64ca5f4b8c url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-attribute-access-control.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Attribute-Based Access Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Attribute-Based Access Control</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-attribute-access-control-release-notes">MCP Attribute-Based Access Control</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Attribute-Based Access Control policy controls access to server tools, resources, and
prompts based on user information such as Tiers, IP, Headers, or Claims. Use the
[Cedar policy language](https://docs.cedarpolicy.com/) to define access rules.

This policy requires that another authentication policy be applied before the MCP Attribute-Based
Access Control policy. For detailed guidance, see [Writing Cedar Rules](#writing-cedar-rules).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Attribute-Based Access Control policy is not supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>Rules to control access to tools, resources, and prompts written in the <a href="https://docs.cedarpolicy.com/">Cedar policy language</a>.</p></div></div></td></tr><tr><td><div><div><p>Cedar Expression</p></div></div></td><td><div><div><p>Cedar expression defining the access rule. For example: <code>permit(principal,action == Action::"tools/call</code> or <code>resource == Tool::"calculator");</code>. To learn more about the Cedar bindings provided by the requests, see <a href="#writing-cedar-rules">Writing Cedar Rules</a>.</p></div></div></td></tr><tr><td><div><div><p>Authentication Type</p></div></div></td><td><div><div><p>Type of authentication used by the authentication policy applied before this policy.</p></div></div></td></tr></tbody></table>

## Writing Cedar Rules

You must apply either an included authentication policy or a custom authentication policy before the
MCP Attribute-Based Access Control policy.

### Included Authentication Policies

The authentication policy you apply affects the available Cedar `principal` bindings:

- Multiple policies can validate Client ID:

  - [Client ID Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-client-id-enforcement)

  - [Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting-sla)

  - [OAuth 2.0 Token Introspection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-oauth-token-introspection) (If Client
    ID enforcement is configured)

  - [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-openid-token-enforcement)
    (If Client ID enforcement is configured)

  - [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation) (If Client ID enforcement is
    configured)

    Policies validating Client ID provide these Cedar bindings:

  - `principal.client_name`: Name of the contract’s client application

  - `principal.principal`: ID of the contract’s client application

  - `principal.properties.slaId`: SLA ID assigned to the contract

- [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation):

  - `principal.properties.claims.<claimName>`: All claims provided by the JWT

- Multiple policies validate basic authentication credentials:

  - [Basic Authentication: Simple Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple)

  - [Basic Authentication: LDAP Policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-ldap)

    Policies validating basic authentication credentials provide these Cedar bindings:

  - `principal.principal`: Username passed as basic auth user

### Custom Authentication Policies

For custom authentication policies, the custom policy must authenticate by using the
`Authentication` injectable. To configure the `Authentication` injectable, see
[Accessing Request Authentication Information](https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features-authentication).

For the Rust `AuthenticationData` structure:

```rust
pub struct AuthenticationData {
    pub principal: Option<String>,
    pub client_id: Option<String>,
    pub client_name: Option<String>,
    pub properties: Value,
}
```

The `AuthenticationData` parameters map to these Cedar bindings:

- `principal`: `principal.principal`

- `client_name`: `principal.client_name`

- `properties`: `principal.properties.*`

## See Also

- [Configuring MCP Access Control Policies](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together)

- [MCP Global Access](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping)

<!-- document id=b0d2519113459512cf9d4c6aa32f225231f756690a90e46fc928a407e252a6ef url=/mulesoft/current/en-us/gateway/1.12/policies-included-mcp-global-access.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, mcp, global access
---

# MCP Global Access Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Global Access</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Restricts which MCP tools, resources, and prompts are exposed by defining Allow and Block rules</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>200 with JSON-RPC error code -32008 — Returned when a call targets a blocked tool, resource, or prompt</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Global Access policy controls which MCP tools, resources, and prompts are available. Use it
to filter the overall list of MCP capabilities that enter your network.

You define rules to allow or block specific items based on their names (for tools and prompts) or
URIs (for resources). When both Allow and Block rules exist, Block rules always take precedence. The
policy applies to:

- Request authorization: The gateway rejects calls to blocked items with a JSON-RPC error stating
  `Access denied to: <name-or-uri>`:

  - `tools/call` requests

  - `resources/read` requests

  - `prompts/get` requests

- Response filtering: The list returned to the client includes only permitted items:

  - `tools/list` responses

  - `resources/list` responses

  - `prompts/list` responses

Filtering applies to both JSON-RPC and SSE response formats.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The MCP Global Access policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>Defines the access control rules. At least one rule is required. Each rule allows or blocks access to matching tools, resources, or prompts.</p></div></div></td></tr><tr><td><div><div><p>Rule</p></div></div></td><td><div><div><p>Defines whether to <strong>Allow</strong> or <strong>Block</strong> access.</p></div></div></td></tr><tr><td><div><div><p>Match type</p></div></div></td><td><div><div><p>Determines how to match the value. Use <strong>literal</strong> for an exact name match or <strong>pattern</strong> for a regular expression.</p></div></div></td></tr><tr><td><div><div><p>Value</p></div></div></td><td><div><div><p>The tool name, resource URI, or prompt name for literal match type, or the regex pattern for pattern match type.</p></div></div></td></tr></tbody></table>

## Rule behavior

Rule order doesn’t matter. The policy evaluates all rules and applies this logic depending on the
combination of rule types are applied:

Only Allow rules

Only items that match at least one Allow rule are permitted. All others are blocked.

Only Block rules

All items are permitted except those that match a Block rule.

Both Allow and Block rules

Only items that match at least one Allow rule and do not match any Block rule are permitted. If an
item matches both an Allow and a Block rule, it is blocked. Items that match no Allow rule are also
blocked.

### Example: Allow list only

To expose only specific tools:

```yaml
rules:
  - rule: Allow
    match_type: literal
    value: get_weather
  - rule: Allow
    match_type: literal
    value: get_user
```

Only `get_weather` and `get_user` can be called. All other tools are blocked and omitted from
`tools/list` responses.

To expose only specific resources by URI pattern:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^file://public/.*
```

In the previous example, only resources matching the `[file://public/](file://public/)` URI pattern
are exposed and blocks all tools and prompts, since their names don’t match the pattern. To scope by
type, combine allow rules that cover each capability you want to expose:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^file://public/.*
  - rule: Allow
    match_type: literal
    value: get_user
```

### Example: Block List Only

To block specific tools and allow everything else:

```yaml
rules:
  - rule: Block
    match_type: literal
    value: admin_delete
  - rule: Block
    match_type: literal
    value: get_secret
```

All tools except `admin_delete` and `get_secret` are exposed.

### Example: Allow and Block with Pattern

To allow a family of tools but block one of them:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^get_.*
  - rule: Block
    match_type: literal
    value: get_secret
```

Tools whose names match the pattern `^get_.*`, such as `get_weather` or `get_user`, are exposed.
`get_secret` is explicitly blocked even though it matches the Allow pattern, because Block takes
precedence.

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/1.12/policies-mcp-access-control-together)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-tool-mapping)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory)

<!-- document id=33612c47a3e5949801e4bf9af4ac8c4e0d6771fc5bab0b2243eda738548bb5c8 url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-global-access.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, mcp, global access
---

# MCP Global Access Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Global Access</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Restricts which MCP tools, resources, and prompts are exposed by defining Allow and Block rules</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-global-access-release-notes">MCP Global Access</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>200 with JSON-RPC error code -32008 — Returned when a call targets a blocked tool, resource, or prompt</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Global Access policy controls which MCP tools, resources, and prompts are available. Use it
to filter the overall list of MCP capabilities that enter your network.

You define rules to allow or block specific items based on their names (for tools and prompts) or
URIs (for resources). When both Allow and Block rules exist, Block rules always take precedence. The
policy applies to:

- Request authorization: The gateway rejects calls to blocked items with a JSON-RPC error stating
  `Access denied to: <name-or-uri>`:

  - `tools/call` requests

  - `resources/read` requests

  - `prompts/get` requests

- Response filtering: The list returned to the client includes only permitted items:

  - `tools/list` responses

  - `resources/list` responses

  - `prompts/list` responses

Filtering applies to both JSON-RPC and SSE response formats.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Global Access policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>Defines the access control rules. At least one rule is required. Each rule allows or blocks access to matching tools, resources, or prompts.</p></div></div></td></tr><tr><td><div><div><p>Rule</p></div></div></td><td><div><div><p>Defines whether to <strong>Allow</strong> or <strong>Block</strong> access.</p></div></div></td></tr><tr><td><div><div><p>Match type</p></div></div></td><td><div><div><p>Determines how to match the value. Use <strong>literal</strong> for an exact name match or <strong>pattern</strong> for a regular expression.</p></div></div></td></tr><tr><td><div><div><p>Value</p></div></div></td><td><div><div><p>The tool name, resource URI, or prompt name for literal match type, or the regex pattern for pattern match type.</p></div></div></td></tr></tbody></table>

## Rule behavior

Rule order doesn’t matter. The policy evaluates all rules and applies this logic depending on the
combination of rule types are applied:

Only Allow rules

Only items that match at least one Allow rule are permitted. All others are blocked.

Only Block rules

All items are permitted except those that match a Block rule.

Both Allow and Block rules

Only items that match at least one Allow rule and do not match any Block rule are permitted. If an
item matches both an Allow and a Block rule, it is blocked. Items that match no Allow rule are also
blocked.

### Example: Allow list only

To expose only specific tools:

```yaml
rules:
  - rule: Allow
    match_type: literal
    value: get_weather
  - rule: Allow
    match_type: literal
    value: get_user
```

Only `get_weather` and `get_user` can be called. All other tools are blocked and omitted from
`tools/list` responses.

To expose only specific resources by URI pattern:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^file://public/.*
```

In the previous example, only resources matching the `[file://public/](file://public/)` URI pattern
are exposed and blocks all tools and prompts, since their names don’t match the pattern. To scope by
type, combine allow rules that cover each capability you want to expose:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^file://public/.*
  - rule: Allow
    match_type: literal
    value: get_user
```

### Example: Block List Only

To block specific tools and allow everything else:

```yaml
rules:
  - rule: Block
    match_type: literal
    value: admin_delete
  - rule: Block
    match_type: literal
    value: get_secret
```

All tools except `admin_delete` and `get_secret` are exposed.

### Example: Allow and Block with Pattern

To allow a family of tools but block one of them:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^get_.*
  - rule: Block
    match_type: literal
    value: get_secret
```

Tools whose names match the pattern `^get_.*`, such as `get_weather` or `get_user`, are exposed.
`get_secret` is explicitly blocked even though it matches the Allow pattern, because Block takes
precedence.

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/1.13/policies-mcp-access-control-together)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

<!-- document id=f649ca14da9c01cdcdf11f04efc260359a8b38a8489a7113fd743f596cebefea url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-global-access.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, mcp, global access
---

# MCP Global Access Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Global Access</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Restricts which MCP tools, resources, and prompts are exposed by defining Allow and Block rules</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-global-access-release-notes">MCP Global Access</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>200 with JSON-RPC error code -32008 — Returned when a call targets a blocked tool, resource, or prompt</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Global Access policy controls which MCP tools, resources, and prompts are available. Use it
to filter the overall list of MCP capabilities that enter your network.

You define rules to allow or block specific items based on their names (for tools and prompts) or
URIs (for resources). When both Allow and Block rules exist, Block rules always take precedence. The
policy applies to:

- Request authorization: The gateway rejects calls to blocked items with a JSON-RPC error stating
  `Access denied to: <name-or-uri>`:

  - `tools/call` requests

  - `resources/read` requests

  - `prompts/get` requests

- Response filtering: The list returned to the client includes only permitted items:

  - `tools/list` responses

  - `resources/list` responses

  - `prompts/list` responses

Filtering applies to both JSON-RPC and SSE response formats.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Global Access policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Rules</p></div></div></td><td><div><div><p>Defines the access control rules. At least one rule is required. Each rule allows or blocks access to matching tools, resources, or prompts.</p></div></div></td></tr><tr><td><div><div><p>Rule</p></div></div></td><td><div><div><p>Defines whether to <strong>Allow</strong> or <strong>Block</strong> access.</p></div></div></td></tr><tr><td><div><div><p>Match type</p></div></div></td><td><div><div><p>Determines how to match the value. Use <strong>literal</strong> for an exact name match or <strong>pattern</strong> for a regular expression.</p></div></div></td></tr><tr><td><div><div><p>Value</p></div></div></td><td><div><div><p>The tool name, resource URI, or prompt name for literal match type, or the regex pattern for pattern match type.</p></div></div></td></tr></tbody></table>

## Rule behavior

Rule order doesn’t matter. The policy evaluates all rules and applies this logic depending on the
combination of rule types are applied:

Only Allow rules

Only items that match at least one Allow rule are permitted. All others are blocked.

Only Block rules

All items are permitted except those that match a Block rule.

Both Allow and Block rules

Only items that match at least one Allow rule and do not match any Block rule are permitted. If an
item matches both an Allow and a Block rule, it is blocked. Items that match no Allow rule are also
blocked.

### Example: Allow list only

To expose only specific tools:

```yaml
rules:
  - rule: Allow
    match_type: literal
    value: get_weather
  - rule: Allow
    match_type: literal
    value: get_user
```

Only `get_weather` and `get_user` can be called. All other tools are blocked and omitted from
`tools/list` responses.

To expose only specific resources by URI pattern:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^file://public/.*
```

In the previous example, only resources matching the `[file://public/](file://public/)` URI pattern
are exposed and blocks all tools and prompts, since their names don’t match the pattern. To scope by
type, combine allow rules that cover each capability you want to expose:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^file://public/.*
  - rule: Allow
    match_type: literal
    value: get_user
```

### Example: Block List Only

To block specific tools and allow everything else:

```yaml
rules:
  - rule: Block
    match_type: literal
    value: admin_delete
  - rule: Block
    match_type: literal
    value: get_secret
```

All tools except `admin_delete` and `get_secret` are exposed.

### Example: Allow and Block with Pattern

To allow a family of tools but block one of them:

```yaml
rules:
  - rule: Allow
    match_type: pattern
    value: ^get_.*
  - rule: Block
    match_type: literal
    value: get_secret
```

Tools whose names match the pattern `^get_.*`, such as `get_weather` or `get_user`, are exposed.
`get_secret` is explicitly blocked even though it matches the Allow pattern, because Block takes
precedence.

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

<!-- document id=024eeb9cee28ef75b16774b7b950cb05658f9593c9a3b96aa2d25dd4aa17ae46 url=/mulesoft/current/en-us/gateway/1.12/policies-included-mcp-payload-optimization.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Payload Optimization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Payload Optimization Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Optimizes MCP tool responses for token consumption by transforming HTML to Markdown and removing unnecessary data</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. The policy modifies response bodies and doesn’t block traffic based on content.</p></td></tr></tbody></table>

## Summary

The MCP Payload Optimization policy reduces LLM token consumption by transforming MCP `tools/call`
responses before they’re returned to the client.

Configure the transformations to:

- Convert HTML to Markdown.

- Remove base64-encoded data.

- Remove JSON fields with null values.

- Remove excessive whitespace.

The policy processes responses when:

- The upstream response has `Content-Type` `application/json` or `text/event-stream` (SSE).

- The body is a JSON-RPC MCP `tools/call` result (including streamed SSE events that carry those
  results).

Configure the minimum response size to skip transformation for small payloads.

The policy uses the `pre_transform_tokens` and `response_tokens` for tool metrics to estimate token
reduction.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The MCP Payload Optimization policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>HTML to Markdown</p></div></div></td><td><div><div><p>Converts HTML content in tool results to Markdown.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Strip Base64</p></div></div></td><td><div><div><p>Detects and removes base64-encoded data from tool results.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Remove Nulls</p></div></div></td><td><div><div><p>Removes JSON fields whose value is null.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Collapse Whitespace</p></div></div></td><td><div><div><p>Removes excess whitespace in text content.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Min Response Size (bytes)</p></div></div></td><td><div><div><p>Minimum response size in bytes to transform. Smaller responses pass through unchanged. Minimum value is <code>0</code>.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>Per-Tool Overrides</p></div></div></td><td><div><div><p>Overrides the policy configuration values for specific tool names. Tools without an override use the global policy configuration. To learn more, see <a href="#tool-overrides">Per-tool overrides</a>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr></tbody></table>

### Per-tool overrides

Use **Per-Tool Overrides** to overide the the response optimization of specific tools. For example,
if whitespace is necessary for a specific tool response but not for others, override **Collapse
Whitespace** for that tool.

You can override the global policy configuration for the **HTML to Markdown**, **Strip Base64**,
**Remove Nulls**, and **Collapse Whitespace** parameters but for not **Min Response Size**.

If you omit a parameter in an override configration, the tool uses the corresponding value from the
global policy configuration.

## See Also

- [MCP Support Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-support)

<!-- document id=afe7959f6e4ce8ad1c67d478058df7c3af563260e69da9d0168f1f092dc31ca0 url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-payload-optimization.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Payload Optimization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Payload Optimization Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Reduces tool response token consumption using one or more configurable methods: remove structural noise, trim oversized responses to match agent intent, or compress repeated structures into TOON</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-payload-optimization-release-notes">MCP Payload Optimization</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Payload Optimization policy reduces LLM token consumption by transforming MCP `tools/call`
responses before they’re returned to the client. The policy operates in three configurable stages:

1.  **Clean Payloads** - Removes structural noise and unnecessary data:

    - Convert HTML to Markdown

    - Remove base64-encoded data

    - Remove JSON fields with null values

    - Remove excessive whitespace

2.  **Smart Response Trimming** - Uses a model proxy to reduce large responses to match the agent’s
    intent, extracting only the information the agent requires.

3.  **Compress Repeated Structures** - Encodes uniform JSON structures into Token-Oriented Object
    Notation (TOON), a lossless format that reduces tokens.

The policy processes responses when:

- The upstream response has a `Content-Type` of `application/json` or `text/event-stream` (SSE).

- The body is a JSON-RPC MCP `tools/call` result (including streamed SSE events that carry those
  results).

Configure the minimum response size to skip transformation for small payloads. Each stage has
independent size thresholds.

The policy uses the `pre_transform_tokens` and `response_tokens` for tool metrics to estimate token
reduction.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Payload Optimization policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>HTML to Markdown</p></div></div></td><td><div><div><p>Converts HTML content in tool results to Markdown.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Strip Base64</p></div></div></td><td><div><div><p>Detects and removes base64-encoded data from tool results.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Remove Nulls</p></div></div></td><td><div><div><p>Removes JSON fields whose value is null.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Collapse Whitespace</p></div></div></td><td><div><div><p>Removes excess whitespace in text content.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Min Response Size (bytes)</p></div></div></td><td><div><div><p>Minimum response size in bytes to transform. Smaller responses pass through unchanged for the four Token Sanitization transforms (<code>HTML to Markdown</code>, <code>Strip Base64</code>, <code>Remove Nulls</code>, <code>Collapse Whitespace</code>). Doesn’t limit TOON encoding or smart response trimming, which have their own thresholds. Minimum value is <code>0</code>.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>Enable Compress Repeated Structures</p></div></div></td><td><div><div><p>Translates JSON-shaped <code>result.content[].text</code> items to TOON to reduce downstream LLM tokens. For more information, see <a href="#compress-repeated-structures">Compress Repeated Structures</a>.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>TOON Min Response Size (bytes)</p></div></div></td><td><div><div><p>Minimum response size in bytes for TOON encoding. Responses smaller than this skip TOON encoding. Minimum value is <code>0</code>.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>Enable Smart Response Trimming</p></div></div></td><td><div><div><p>When enabled, a model proxy distills large tool responses down to match the caller’s declared intent (the <code>expected_info</code> of the request), reducing tokens returned to the model.For more information, see <a href="#smart-response-trimming">Smart Response Trimming</a>.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Model Proxy URL</p></div></div></td><td><div><div><p>The endpoint of the model proxy service used for Smart Response Trimming (for example, <code><a href="http://llmproxy.svc.cluster.local/v1/chat/completions">http://llmproxy.svc.cluster.local/v1/chat/completions</a></code>). Must be an OpenAI-compatible <code>/chat/completions</code> endpoint. Required when Smart Response Trimming is enabled.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Model Proxy ID</p></div></div></td><td><div><div><p>Identifier of the selected Model Proxy asset, stored for reference. This value is parsed and retained but not used at runtime by the policy.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Model-Based Routing</p></div></div></td><td><div><div><p>Determines how the model proxy selects the target model. When disabled (default), the proxy owns model selection (Semantic Routing). When enabled, the caller selects the model via the <code>LLM Model</code> parameter (Model-Based Routing).</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>LLM Model</p></div></div></td><td><div><div><p>Model name sent in the <code>/chat/completions</code> request body (for example, <code>gpt-4o-mini</code>). Required when <strong>Model-Based Routing</strong> is enabled.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p>Client ID for model proxy authentication. Sent as a <code>client_id</code> request header.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Client Secret</p></div></div></td><td><div><div><p>Client secret for model proxy authentication. Sent as a <code>client_secret</code> request header.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Threshold Bytes</p></div></div></td><td><div><div><p>Smart Response Trimming runs only when the post-sanitize content length exceeds this threshold (in bytes). Payloads below this threshold pass through with sanitize-only results.</p></div></div></td><td><div><div><p><code>8000</code></p></div></div></td></tr><tr><td><div><div><p>LLM Timeout (ms)</p></div></div></td><td><div><div><p>Timeout in milliseconds for each model proxy request. If the proxy exceeds this timeout, the call fails and only completes the <strong>Clean Payloads</strong> step.</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr><tr><td><div><div><p>Per-Tool Overrides</p></div></div></td><td><div><div><p>Overrides the policy configuration values for specific tool names. Tools without an override use the global policy configuration. To learn more, see <a href="#tool-overrides">Per-tool overrides</a>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr></tbody></table>

### Per-tool overrides

Use **Per-Tool Overrides** to override the response optimization of specific tools. For example, if
whitespace is necessary for a specific tool response but not for others, override **Collapse
Whitespace** for that tool.

You can override the global policy configuration for the **HTML to Markdown**, **Strip Base64**,
**Remove Nulls**, and **Collapse Whitespace** parameters. You cannot override **Min Response Size**,
**TOON Min Response Size**, **Enable Compress Repeated Structures**, or **Smart Response Trimming**
on a per-tool basis. Both TOON encoding and Smart Response Trimming are global settings that apply
to all eligible tool responses.

If you omit a parameter in an override configuration, the tool uses the corresponding value from the
global policy configuration.

#### Example per-tool override

For a tool that legitimately returns base64-encoded images, you can disable **Strip Base64** for
that specific tool:

```yaml
tool_overrides:
  - tool_name: generate_image
    strip_base64: false
```

## Transformation Order

The policy applies optimizations in three stages:

### Stage 1: Clean Payloads

String transforms are applied to each eligible string value in this order:

1.  **HTML to Markdown** — Converts HTML documents or fragments to Markdown.

2.  **Strip Base64** — Replaces detected base64 blobs with a short `<stripped: N bytes>`
    placeholder.

3.  **Collapse Whitespace** — Normalizes runs of whitespace.

Then the structural transform is applied:

4.  **Remove Nulls** — Removes JSON fields with null values (applied once after string transforms).

### Stage 2: Smart Response Trimming

When enabled, Smart Response Trimming runs after Token Sanitization:

5.  **Intent Extraction** — A model proxy distills the sanitized content to match the agent’s
    declared intent, reducing token count further.

### Stage 3: Compress Repeated Structures

When enabled, TOON encoding runs last:

6.  **TOON Encoding** — Encodes eligible JSON content items into TOON format (runs on
    already-cleaned and optionally-extracted content).

## Smart Response Trimming

Smart Response Trimming uses a model proxy to distill large tool responses to match the agent’s
declared intent. When enabled, the policy:

1.  Applies the Token Sanitization transforms (HTML to Markdown, Strip Base64, Collapse Whitespace,
    Remove Nulls).

2.  Checks if the sanitized content exceeds the **Threshold Bytes** parameter (default: 8000 bytes)
    and includes `expected_info`

3.  Sends the sanitized content to the configured model proxy.

4.  Replaces the original content with the LLM extracted response if it’s smaller than the sanitized
    version.

Smart Response Trimming:

- Requires a model proxy endpoint configured via **Model Proxy URL**.

- Requires `expected_info` to be present and non-empty in the request. The extractor only runs when
  the caller declares their intent.

- Is fail-open. If there is any LLM failure (timeout, transport error, non-2xx status), the policy
  falls back to the result from **Clean payloads**.

- Processes `content[0]` only when it is `type: "text"`. Other content entries are left untouched.

- Uses client credentials (**Client ID** and **Client Secret**) for model proxy authentication, sent
  as separate `client_id` and `client_secret` request headers (not HTTP Basic Auth).

- Includes an output guard that rejects extractions larger than the sanitized input.

- Makes exactly one LLM call per response.

- Works with both JSON (`application/json`) and Server-Sent Event (`text/event-stream`) responses.
  When enabled, SSE responses are buffered to allow complete content extraction.

## Compress Repeated Structures

TOON is a compact, lossless, JSON-equivalent text format that reduces LLM token consumption for
structured data. When **Enable Compress Repeated Structures** is enabled, the policy translates
eligible JSON-shaped content items into TOON format.

TOON encoding:

- Runs after all other transforms.

- Applies to only the shapes that TOON can shrink, for example, uniform-scalar arrays of objects.

- Preserves or reduces payload size (never inflates).

- Is a global setting with no per-tool overrides.

- Uses the **TOON Min Response Size (bytes)** threshold, independent of the **Min Response Size
  (bytes)** threshold used for other transforms.

A payload can be large enough for TOON encoding but too small for Token Sanitization transforms, or
vice versa, because they use independent thresholds.

## See Also

- [MCP Support Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-support)

<!-- document id=ac2c0950996350c8ea7c76d111849699daaad76a9adcb48210affe6dc3a23b07 url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-payload-optimization.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Payload Optimization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Payload Optimization Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Reduces tool response token consumption using one or more configurable methods: remove structural noise, trim oversized responses to match agent intent, or compress repeated structures into TOON</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.12.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-payload-optimization-release-notes">MCP Payload Optimization</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Payload Optimization policy reduces LLM token consumption by transforming MCP `tools/call`
responses before they’re returned to the client. The policy operates in three configurable stages:

1.  **Clean Payloads** - Removes structural noise and unnecessary data:

    - Convert HTML to Markdown

    - Remove base64-encoded data

    - Remove JSON fields with null values

    - Remove excessive whitespace

2.  **Smart Response Trimming** - Uses a model proxy to reduce large responses to match the agent’s
    intent, extracting only the information the agent requires.

3.  **Compress Repeated Structures** - Encodes uniform JSON structures into Token-Oriented Object
    Notation (TOON), a lossless format that reduces tokens.

The policy processes responses when:

- The upstream response has a `Content-Type` of `application/json` or `text/event-stream` (SSE).

- The body is a JSON-RPC MCP `tools/call` result (including streamed SSE events that carry those
  results).

Configure the minimum response size to skip transformation for small payloads. Each stage has
independent size thresholds.

The policy uses the `pre_transform_tokens` and `response_tokens` for tool metrics to estimate token
reduction.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Payload Optimization policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>HTML to Markdown</p></div></div></td><td><div><div><p>Converts HTML content in tool results to Markdown.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Strip Base64</p></div></div></td><td><div><div><p>Detects and removes base64-encoded data from tool results.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Remove Nulls</p></div></div></td><td><div><div><p>Removes JSON fields whose value is null.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Collapse Whitespace</p></div></div></td><td><div><div><p>Removes excess whitespace in text content.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Min Response Size (bytes)</p></div></div></td><td><div><div><p>Minimum response size in bytes to transform. Smaller responses pass through unchanged for the four Token Sanitization transforms (<code>HTML to Markdown</code>, <code>Strip Base64</code>, <code>Remove Nulls</code>, <code>Collapse Whitespace</code>). Doesn’t limit TOON encoding or smart response trimming, which have their own thresholds. Minimum value is <code>0</code>.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>Enable Compress Repeated Structures</p></div></div></td><td><div><div><p>Translates JSON-shaped <code>result.content[].text</code> items to TOON to reduce downstream LLM tokens. For more information, see <a href="#compress-repeated-structures">Compress Repeated Structures</a>.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>TOON Min Response Size (bytes)</p></div></div></td><td><div><div><p>Minimum response size in bytes for TOON encoding. Responses smaller than this skip TOON encoding. Minimum value is <code>0</code>.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>Enable Smart Response Trimming</p></div></div></td><td><div><div><p>When enabled, a model proxy distills large tool responses down to match the caller’s declared intent (the <code>expected_info</code> of the request), reducing tokens returned to the model.For more information, see <a href="#smart-response-trimming">Smart Response Trimming</a>.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Model Proxy URL</p></div></div></td><td><div><div><p>The endpoint of the model proxy service used for Smart Response Trimming (for example, <code><a href="http://llmproxy.svc.cluster.local/v1/chat/completions">http://llmproxy.svc.cluster.local/v1/chat/completions</a></code>). Must be an OpenAI-compatible <code>/chat/completions</code> endpoint. Required when Smart Response Trimming is enabled.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Model Proxy ID</p></div></div></td><td><div><div><p>Identifier of the selected Model Proxy asset, stored for reference. This value is parsed and retained but not used at runtime by the policy.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Model-Based Routing</p></div></div></td><td><div><div><p>Determines how the model proxy selects the target model. When disabled (default), the proxy owns model selection (Semantic Routing). When enabled, the caller selects the model via the <code>LLM Model</code> parameter (Model-Based Routing).</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>LLM Model</p></div></div></td><td><div><div><p>Model name sent in the <code>/chat/completions</code> request body (for example, <code>gpt-4o-mini</code>). Required when <strong>Model-Based Routing</strong> is enabled.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p>Client ID for model proxy authentication. Sent as a <code>client_id</code> request header.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Client Secret</p></div></div></td><td><div><div><p>Client secret for model proxy authentication. Sent as a <code>client_secret</code> request header.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr><tr><td><div><div><p>Threshold Bytes</p></div></div></td><td><div><div><p>Smart Response Trimming runs only when the post-sanitize content length exceeds this threshold (in bytes). Payloads below this threshold pass through with sanitize-only results.</p></div></div></td><td><div><div><p><code>8000</code></p></div></div></td></tr><tr><td><div><div><p>LLM Timeout (ms)</p></div></div></td><td><div><div><p>Timeout in milliseconds for each model proxy request. If the proxy exceeds this timeout, the call fails and only completes the <strong>Clean Payloads</strong> step.</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr><tr><td><div><div><p>Per-Tool Overrides</p></div></div></td><td><div><div><p>Overrides the policy configuration values for specific tool names. Tools without an override use the global policy configuration. To learn more, see <a href="#tool-overrides">Per-tool overrides</a>.</p></div></div></td><td><div><div><p>N/A</p></div></div></td></tr></tbody></table>

### Per-tool overrides

Use **Per-Tool Overrides** to override the response optimization of specific tools. For example, if
whitespace is necessary for a specific tool response but not for others, override **Collapse
Whitespace** for that tool.

You can override the global policy configuration for the **HTML to Markdown**, **Strip Base64**,
**Remove Nulls**, and **Collapse Whitespace** parameters. You cannot override **Min Response Size**,
**TOON Min Response Size**, **Enable Compress Repeated Structures**, or **Smart Response Trimming**
on a per-tool basis. Both TOON encoding and Smart Response Trimming are global settings that apply
to all eligible tool responses.

If you omit a parameter in an override configuration, the tool uses the corresponding value from the
global policy configuration.

#### Example per-tool override

For a tool that legitimately returns base64-encoded images, you can disable **Strip Base64** for
that specific tool:

```yaml
tool_overrides:
  - tool_name: generate_image
    strip_base64: false
```

## Transformation Order

The policy applies optimizations in three stages:

### Stage 1: Clean Payloads

String transforms are applied to each eligible string value in this order:

1.  **HTML to Markdown** — Converts HTML documents or fragments to Markdown.

2.  **Strip Base64** — Replaces detected base64 blobs with a short `<stripped: N bytes>`
    placeholder.

3.  **Collapse Whitespace** — Normalizes runs of whitespace.

Then the structural transform is applied:

4.  **Remove Nulls** — Removes JSON fields with null values (applied once after string transforms).

### Stage 2: Smart Response Trimming

When enabled, Smart Response Trimming runs after Token Sanitization:

5.  **Intent Extraction** — A model proxy distills the sanitized content to match the agent’s
    declared intent, reducing token count further.

### Stage 3: Compress Repeated Structures

When enabled, TOON encoding runs last:

6.  **TOON Encoding** — Encodes eligible JSON content items into TOON format (runs on
    already-cleaned and optionally-extracted content).

## Smart Response Trimming

Smart Response Trimming uses a model proxy to distill large tool responses to match the agent’s
declared intent. When enabled, the policy:

1.  Applies the Token Sanitization transforms (HTML to Markdown, Strip Base64, Collapse Whitespace,
    Remove Nulls).

2.  Checks if the sanitized content exceeds the **Threshold Bytes** parameter (default: 8000 bytes)
    and includes `expected_info`

3.  Sends the sanitized content to the configured model proxy.

4.  Replaces the original content with the LLM extracted response if it’s smaller than the sanitized
    version.

Smart Response Trimming:

- Requires a model proxy endpoint configured via **Model Proxy URL**.

- Requires `expected_info` to be present and non-empty in the request. The extractor only runs when
  the caller declares their intent.

- Is fail-open. If there is any LLM failure (timeout, transport error, non-2xx status), the policy
  falls back to the result from **Clean payloads**.

- Processes `content[0]` only when it is `type: "text"`. Other content entries are left untouched.

- Uses client credentials (**Client ID** and **Client Secret**) for model proxy authentication, sent
  as separate `client_id` and `client_secret` request headers (not HTTP Basic Auth).

- Includes an output guard that rejects extractions larger than the sanitized input.

- Makes exactly one LLM call per response.

- Works with both JSON (`application/json`) and Server-Sent Event (`text/event-stream`) responses.
  When enabled, SSE responses are buffered to allow complete content extraction.

## Compress Repeated Structures

TOON is a compact, lossless, JSON-equivalent text format that reduces LLM token consumption for
structured data. When **Enable Compress Repeated Structures** is enabled, the policy translates
eligible JSON-shaped content items into TOON format.

TOON encoding:

- Runs after all other transforms.

- Applies to only the shapes that TOON can shrink, for example, uniform-scalar arrays of objects.

- Preserves or reduces payload size (never inflates).

- Is a global setting with no per-tool overrides.

- Uses the **TOON Min Response Size (bytes)** threshold, independent of the **Min Response Size
  (bytes)** threshold used for other transforms.

A payload can be large enough for TOON encoding but too small for Token Sanitization transforms, or
vice versa, because they use independent thresholds.

## See Also

- [MCP Support Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support)

<!-- document id=ae774700eaf1d6ed7e4c96c78402ba74ddb9326a3b7645753117463aefcb57de url=/mulesoft/current/en-us/gateway/1.12/policies-included-mcp-pii-detector.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Personally Identifiable Information (PII) Detector Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP PII Detector Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks elicitation responses containing personally identifiable information (PII) from reaching MCP servers</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. The policy reports a policy violation when PII is detected.</p></td></tr></tbody></table>

## Summary

The MCP PII Detector policy blocks elicitation responses containing personally identifiable
information (PII) from reaching MCP servers.

When PII is detected in the elicitation response `result` field, the policy:

- Reports a policy violation.

- Sends a modified response to the MCP server that the request was declined and includes the message
  `PII data requested or found in user response`.

The policy doesn’t send a response to the client when PII is detected.

The policy only scans JSON-RPC responses that contain a `result` field. JSON-RPC requests with a
`method` field are ignored.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The MCP PII Detector policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Entities</p></div></div></td><td><div><div><p>Array that defines the types of PII to detect. You can select multiple PII types. Supported values are <code>Email</code>, <code>US SSN</code>, <code>Credit Card</code>, <code>Phone Number</code>.<br>For more information, see <a href="#pii-types">PII Types</a>.</p></div></div></td></tr></tbody></table>

### PII Types

When you configure an MCP PII Detector policy, you can choose which types of PII to detect:

<table><colgroup><col> <col></colgroup><thead><tr><th>PII Type</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Email</p></div></div></td><td><div><div><p>Standard email addresses such as <code>User.Name+tag@example.com</code>.</p></div></div></td></tr><tr><td><div><div><p>US SSN</p></div></div></td><td><div><div><p>United States Social Security Numbers (SSNs) in the standard format: <code>XXX-XX-XXXX</code> where each <code>X</code> is a digit. For example, <code>123-45-6789</code>.</p></div></div></td></tr><tr><td><div><div><p>Credit Card</p></div></div></td><td><div><div><p>Credit card numbers in the form of four groups of four digits, separated by optional spaces or hyphens. For example,<code>1234-5678-9012-3456</code>, <code>1234 5678 9012 3456</code>, or <code>1234567890123456</code>.</p></div></div></td></tr><tr><td><div><div><p>Phone Number</p></div></div></td><td><div><div><p>United States phone numbers in various formats, with or without country code, parentheses, spaces, hyphens, or dots. For example, <code>123-456-7890</code>, <code>(123) 456-7890</code>, <code>123.456.7890</code>, <code>+1 123 456 7890</code>, or <code>1234567890</code>.</p></div></div></td></tr></tbody></table>

<!-- document id=bb57de76a3b684876c84a0f2f96ef56def6b0a56e44069ad0ef96cc29e967924 url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-pii-detector.md -->

# MCP Personally Identifiable Information (PII) Detector Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP PII Detector Policy</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detects personally identifiable information (PII) in Model Context Protocol (MCP) JSON-RPC traffic on both the request and response sides</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.9.3</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-pii-detector-release-notes" class="xref page">MCP PII Detector</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy. The policy reports a policy violation when PII is detected.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The MCP PII Detector policy detects personally identifiable information (PII) in Model Context Protocol (MCP) JSON-RPC traffic on both the request and response sides.

When PII is detected, you can configure the policy to reject the request or response, log findings, or log masked findings. The policy reports a policy violation when PII is detected.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#omni-gateway-local-mode)Omni Gateway Local Mode

The MCP PII Detector policy isn’t supported in Local Mode.

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Element</th>
<th class="tableblock halign-left valign-top">Required</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>PII Types</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Yes</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of built-in PII types to detect. Supported values are <strong>Email</strong>, <strong>US SSN</strong>, <strong>Credit Card</strong>, and <strong>Phone Number</strong>. For more information, see <a href="#pii-types">PII Types</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Custom PII Patterns</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of custom regex patterns to detect additional sensitive values. Define a name and regex pattern for each array entry. For example, use <code>name: AWS Access Key</code> and <code>pattern: AKIA[0-9A-Z]{16}</code> to detect AWS access keys.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Action</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Action to take when PII is detected. Supported values are <strong>Reject</strong>, <strong>Log</strong>, and <strong>Log and mask</strong>. Default is <strong>Log</strong>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#how-this-policy-works)How This Policy Works

The MCP PII Detector policy is symmetric: it scans both request and response sides of MCP JSON-RPC traffic for PII. It recursively inspects all string values in both `params.` **(for requests) and `result.`** (for responses).

The policy scans:

- **JSON-RPC requests**: All string values under `params.*` from client to server
- **JSON-RPC responses**: All string values under `result.*` from server to client, including nested objects and arrays
- **Elicitation responses**: JSON-RPC responses sent from client back to server (MCP elicitation pattern)
- **SSE streams**: Each `data:` payload in Server-Sent Events (MCP Streamable HTTP transport)

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 28.5714%;">
<col style="width: 28.5714%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Traffic Type</th>
<th class="tableblock halign-left valign-top">Reject</th>
<th class="tableblock halign-left valign-top">Log</th>
<th class="tableblock halign-left valign-top">Log and Mask</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request processing</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks the request with HTTP 403 error response. The upstream server never receives the request.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the request and logs findings with actual PII values.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the request and logs findings with masked values.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Response processing (application/json)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks the response with HTTP 403 error response. The client doesn’t receive the original response containing PII.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the response and logs findings with actual PII values.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites every string under <code>result</code> with masked values and forwards the sanitized response.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Elicitation responses (client → server)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites the result to indicate the response was declined and forwards the sanitized body to the server.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the response and logs findings.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the response and logs masked findings.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE streams (text/event-stream)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Entire stream is replaced with a single JSON-RPC error envelope and Content-Type changes to application/json.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the stream unchanged and logs findings.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each event’s result strings are rewritten with masked variants while preserving SSE framing.</p></td>
</tr>
</tbody>
</table>

The policy detects overlapping PII patterns and keeps the longest (most specific) match. For example, a credit card number with delimiters that could also match an SSN pattern is detected as a credit card.

## [](#pii-types)PII Types

When you configure an MCP PII Detector policy, you can choose which types of PII to detect:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">PII Type</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Email</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Standard email addresses such as <code>User.Name+tag@example.com</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>US SSN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>United States Social Security Numbers (SSNs), including formats with various delimiters such as <code>123-45-6789</code>, <code>123 45 6789</code>, <code>123.45.6789</code>, <code>123,45,6789</code>, <code>123/45/6789</code>, <code>123\45\6789</code>, or <code>123456789</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Credit Card</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Credit card numbers for Visa, MasterCard, American Express, and Discover, with or without separators. Examples: <code>4111-1111-1111-1111</code>, <code>4111 1111 1111 1111</code>, <code>4111111111111111</code>, <code>4111.1111.1111.1111</code>, <code>5500-0000-0000-0004</code>, <code>3782-822463-10005</code>, <code>6011-0000-0000-0004</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Phone Number</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Phone numbers in common domestic and international formats based on ITU E.164 country codes. Examples include US numbers like <code>(555) 123-4567</code>, <code>555-123-4567</code>, <code>+1-555-123-4567</code>, and international numbers like <code>+91 98765 43210</code>, <code>+44 20 7946 0958</code>, <code>+49 30 12345678</code>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#example-request-and-logging)Example Request and Logging

This example shows a request containing PII and the corresponding log output for different action configurations:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "send_email",
    "arguments": {
      "to": "john.doe@example.com",
      "message": "Contact info: phone is (555) 123-4567, SSN is 123-45-6789"
    }
  }
}
```

- Log
- Log and Mask
- Reject

When the action is set to **Log**, the policy logs detect PII with the actual values:

```text
[accessLog] PII detected in request (log only): [{"pii_type": "Email", "value": "john.doe@example.com", "start": 0, "end": 20}, {"pii_type": "Phone", "value": "(555) 123-4567", "start": 0, "end": 14}, {"pii_type": "SSN", "value": "123-45-6789", "start": 0, "end": 11}]
```

When the action is set to **Log and mask**, the policy logs detect PII with masked values:

```text
[accessLog] PII detected in request (log only): [{"pii_type": "Email", "masked_value": "****@example.com", "start": 0, "end": 20}, {"pii_type": "Phone", "masked_value": "+1******567", "start": 0, "end": 14}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 0, "end": 11}]
```

When the action is set to **Reject**, the policy blocks the request, logs masked findings, and returns an HTTP 403 error response:

Log output:

```text
[accessLog] PII detected in request and declined: [{"pii_type": "Email", "masked_value": "****@example.com", "start": 0, "end": 20}, {"pii_type": "Phone", "masked_value": "+1******567", "start": 0, "end": 14}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 0, "end": 11}]
```

Error response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Request payload validation error",
    "data": {
      "reason": "policy_pii_detected",
      "phase": "request",
      "policy": "mcp-pii-detector",
      "findings": [
        { "pii_type": "Email", "masked_value": "****@example.com" },
        { "pii_type": "Phone", "masked_value": "+1******567" },
        { "pii_type": "SSN", "masked_value": "***-**-*789" }
      ]
    }
  }
}
```

The upstream server never receives the original request containing PII.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">Request-side rejections use error code <code>-32602</code> (Invalid params) to indicate a client error, while response-side rejections use error code <code>-32603</code> (Internal error) to indicate the server response could not be safely returned.</td></tr></tbody></table>

## [](#example-response-and-logging)Example Response and Logging

This example shows a server response containing PII and the corresponding behavior for different action configurations:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "User contact: john.doe@example.com, SSN: 123-45-6789"
      }
    ]
  }
}
```

- Log
- Log and Mask
- Reject

When the action is set to **Log**, the policy forwards the response and logs detected PII with actual values:

```text
[accessLog] PII detected in server response (log only): [{"pii_type": "Email", "value": "john.doe@example.com", "start": 14, "end": 34}, {"pii_type": "SSN", "value": "123-45-6789", "start": 41, "end": 52}]
```

When the action is set to **Log and mask**, the policy rewrites the response with masked values and logs masked findings:

Response sent to client:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "User contact: ****@example.com, SSN: ***-**-*789"
      }
    ]
  }
}
```

Log output:

```text
[accessLog] PII detected in server response (masked in body): [{"pii_type": "Email", "masked_value": "****@example.com", "start": 14, "end": 34}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 41, "end": 52}]
```

When the action is set to **Reject**, the policy blocks the response, logs masked findings, and returns an HTTP 403 error:

Log output:

```text
[accessLog] PII detected in server response and declined: [{"pii_type": "Email", "masked_value": "****@example.com", "start": 14, "end": 34}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 41, "end": 52}]
```

Error response:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "reason": "policy_pii_detected",
      "phase": "response",
      "policy": "mcp-pii-detector",
      "findings": [
        { "pii_type": "Email", "masked_value": "****@example.com" },
        { "pii_type": "SSN", "masked_value": "***-**-*789" }
      ]
    }
  }
}
```

The client does not receive the original response containing PII.

### [](#elicitation-response-example)Elicitation Response Example

When a client sends a JSON-RPC response back to the server (MCP elicitation pattern) containing PII, and the action is set to **Reject**, the policy rewrites the result:

Original elicitation response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "User SSN is 123-45-6789"
      }
    ]
  }
}
```

Sanitized response forwarded to server:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "decline",
    "reason": "Elicitation response declined due to detected PII"
  }
}
```

### [](#custom-pattern-example)Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern in a request:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "deploy",
    "arguments": {
      "key": "AKIAIOSFODNN7EXAMPLE"
    }
  }
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy logs:

```text
[accessLog] PII detected in request (log only): [{"pii_type": "AWS Access Key", "value": "AKIAIOSFODNN7EXAMPLE", "start": 0, "end": 20}]
```

## [](#server-sent-events-sse-considerations)Server-Sent Events (SSE) Considerations

When the MCP server uses Server-Sent Events (text/event-stream) for streaming responses, the policy buffers and processes the entire stream:

- **Log**: The stream is forwarded unchanged with raw PII values logged.
- **Log and mask**: Each event’s result strings are rewritten with masked values while preserving SSE framing (event names, IDs, comments).
- **Reject**: The entire stream is replaced with a single JSON-RPC error envelope, and the Content-Type changes to application/json with HTTP 403 status.

<table><tbody><tr><td class="icon"><i class="fa icon-important" title="Important"></i></td><td class="content">SSE buffering is suitable for short-lived tool-call responses but might not be appropriate for long-lived server-pushed streams. For notification streams or progress updates, use the <strong>Log</strong> action to avoid buffering.</td></tr></tbody></table>

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">When <strong>Reject</strong> is applied to an SSE stream, the response Content-Type changes from text/event-stream to application/json. Clients that strictly require SSE formatting might need to handle this change.</td></tr></tbody></table>

## [](#compliance-and-data-flow)Compliance and Data Flow

This table shows where raw PII values appear based on the configured action:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 40%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Action</th>
<th class="tableblock halign-left valign-top">Request/Response Body on Wire</th>
<th class="tableblock halign-left valign-top">Access Log</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reject</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked (findings in error.data.findings[].masked_value)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Log and mask</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked (rewrites response body) or unchanged (forwards request unchanged)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Log</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwarded unchanged (raw PII flows through)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Raw</p></td>
</tr>
</tbody>
</table>

<table><tbody><tr><td class="icon"><i class="fa icon-important" title="Important"></i></td><td class="content"><strong>Reject</strong> is the strict mode that never writes raw PII values anywhere (wire or log). If you need raw values in logs for diagnostics, use the <strong>Log</strong> action instead.</td></tr></tbody></table>

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">For the A2A PII Detector policy, the <strong>Log and mask</strong> action only masks the access log, not the request body. The MCP PII Detector’s <strong>Log and mask</strong> action rewrites response bodies but forwards request bodies unchanged.</td></tr></tbody></table>

## [](#see-also)See Also

- [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-pii-detector)
- [LLM PII Detection Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-llm-pii-detection)

<!-- document id=00de81b19d0704a2b612ebc45328563cf68dcb8c563a0d1fbcb66d66d00102ef url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-pii-detector.md -->

# MCP Personally Identifiable Information (PII) Detector Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP PII Detector Policy</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks elicitation responses containing personally identifiable information (PII) from reaching MCP servers</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">MCP</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.9.3</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-pii-detector-release-notes" class="xref page">MCP PII Detector</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy. The policy reports a policy violation when PII is detected.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The MCP PII Detector policy detects personally identifiable information (PII) in Model Context Protocol (MCP) JSON-RPC traffic on both the request and response sides.

When PII is detected, you can configure the policy to reject the request or response, log findings, or log masked findings. The policy reports a policy violation when PII is detected.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#omni-gateway-local-mode)Omni Gateway Local Mode

The MCP PII Detector policy isn’t supported in Local Mode.

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Element</th>
<th class="tableblock halign-left valign-top">Required</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>PII Types</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Yes</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of built-in PII types to detect. Supported values are <strong>Email</strong>, <strong>US SSN</strong>, <strong>Credit Card</strong>, and <strong>Phone Number</strong>. For more information, see <a href="#pii-types">PII Types</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Custom PII Patterns</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of custom regex patterns to detect additional sensitive values. Define a name and regex pattern for each array entry. For example, use <code>name: AWS Access Key</code> and <code>pattern: AKIA[0-9A-Z]{16}</code> to detect AWS access keys.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Action</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Action to take when PII is detected. Supported values are <strong>Reject</strong>, <strong>Log</strong>, and <strong>Log and mask</strong>. Default is <strong>Log</strong>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#how-this-policy-works)How This Policy Works

The MCP PII Detector policy is symmetric: it scans both request and response sides of MCP JSON-RPC traffic for PII. It recursively inspects all string values in both `params.` **(for requests) and `result.`** (for responses).

The policy scans:

- **JSON-RPC requests**: All string values under `params.*` from client to server
- **JSON-RPC responses**: All string values under `result.*` from server to client, including nested objects and arrays
- **Elicitation responses**: JSON-RPC responses sent from client back to server (MCP elicitation pattern)
- **SSE streams**: Each `data:` payload in Server-Sent Events (MCP Streamable HTTP transport)

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 28.5714%;">
<col style="width: 28.5714%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Traffic Type</th>
<th class="tableblock halign-left valign-top">Reject</th>
<th class="tableblock halign-left valign-top">Log</th>
<th class="tableblock halign-left valign-top">Log and Mask</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request processing</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks the request with HTTP 403 error response. The upstream server never receives the request.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the request and logs findings with actual PII values.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the request and logs findings with masked values.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Response processing (application/json)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blocks the response with HTTP 403 error response. The client doesn’t receive the original response containing PII.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the response and logs findings with actual PII values.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites every string under <code>result</code> with masked values and forwards the sanitized response.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Elicitation responses (client → server)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Rewrites the result to indicate the response was declined and forwards the sanitized body to the server.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the response and logs findings.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the response and logs masked findings.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE streams (text/event-stream)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Entire stream is replaced with a single JSON-RPC error envelope and Content-Type changes to application/json.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwards the stream unchanged and logs findings.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Each event’s result strings are rewritten with masked variants while preserving SSE framing.</p></td>
</tr>
</tbody>
</table>

The policy detects overlapping PII patterns and keeps the longest (most specific) match. For example, a credit card number with delimiters that could also match an SSN pattern is detected as a credit card.

## [](#pii-types)PII Types

When you configure an MCP PII Detector policy, you can choose which types of PII to detect:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">PII Type</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Email</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Standard email addresses such as <code>User.Name+tag@example.com</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>US SSN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>United States Social Security Numbers (SSNs), including formats with various delimiters such as <code>123-45-6789</code>, <code>123 45 6789</code>, <code>123.45.6789</code>, <code>123,45,6789</code>, <code>123/45/6789</code>, <code>123\45\6789</code>, or <code>123456789</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Credit Card</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Credit card numbers for Visa, MasterCard, American Express, and Discover, with or without separators. Examples: <code>4111-1111-1111-1111</code>, <code>4111 1111 1111 1111</code>, <code>4111111111111111</code>, <code>4111.1111.1111.1111</code>, <code>5500-0000-0000-0004</code>, <code>3782-822463-10005</code>, <code>6011-0000-0000-0004</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Phone Number</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Phone numbers in common domestic and international formats based on ITU E.164 country codes. Examples include US numbers like <code>(555) 123-4567</code>, <code>555-123-4567</code>, <code>+1-555-123-4567</code>, and international numbers like <code>+91 98765 43210</code>, <code>+44 20 7946 0958</code>, <code>+49 30 12345678</code>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#example-request-and-logging)Example Request and Logging

This example shows a request containing PII and the corresponding log output for different action configurations:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "send_email",
    "arguments": {
      "to": "john.doe@example.com",
      "message": "Contact info: phone is (555) 123-4567, SSN is 123-45-6789"
    }
  }
}
```

- Log
- Log and Mask
- Reject

When the action is set to **Log**, the policy logs detect PII with the actual values:

```text
[accessLog] PII detected in request (log only): [{"pii_type": "Email", "value": "john.doe@example.com", "start": 0, "end": 20}, {"pii_type": "Phone", "value": "(555) 123-4567", "start": 0, "end": 14}, {"pii_type": "SSN", "value": "123-45-6789", "start": 0, "end": 11}]
```

When the action is set to **Log and mask**, the policy logs detect PII with masked values:

```text
[accessLog] PII detected in request (log only): [{"pii_type": "Email", "masked_value": "****@example.com", "start": 0, "end": 20}, {"pii_type": "Phone", "masked_value": "+1******567", "start": 0, "end": 14}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 0, "end": 11}]
```

When the action is set to **Reject**, the policy blocks the request, logs masked findings, and returns an HTTP 403 error response:

Log output:

```text
[accessLog] PII detected in request and declined: [{"pii_type": "Email", "masked_value": "****@example.com", "start": 0, "end": 20}, {"pii_type": "Phone", "masked_value": "+1******567", "start": 0, "end": 14}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 0, "end": 11}]
```

Error response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Request payload validation error",
    "data": {
      "reason": "policy_pii_detected",
      "phase": "request",
      "policy": "mcp-pii-detector",
      "findings": [
        { "pii_type": "Email", "masked_value": "****@example.com" },
        { "pii_type": "Phone", "masked_value": "+1******567" },
        { "pii_type": "SSN", "masked_value": "***-**-*789" }
      ]
    }
  }
}
```

The upstream server never receives the original request containing PII.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">Request-side rejections use error code <code>-32602</code> (Invalid params) to indicate a client error, while response-side rejections use error code <code>-32603</code> (Internal error) to indicate the server response could not be safely returned.</td></tr></tbody></table>

## [](#example-response-and-logging)Example Response and Logging

This example shows a server response containing PII and the corresponding behavior for different action configurations:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "User contact: john.doe@example.com, SSN: 123-45-6789"
      }
    ]
  }
}
```

- Log
- Log and Mask
- Reject

When the action is set to **Log**, the policy forwards the response and logs detected PII with actual values:

```text
[accessLog] PII detected in server response (log only): [{"pii_type": "Email", "value": "john.doe@example.com", "start": 14, "end": 34}, {"pii_type": "SSN", "value": "123-45-6789", "start": 41, "end": 52}]
```

When the action is set to **Log and mask**, the policy rewrites the response with masked values and logs masked findings:

Response sent to client:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "User contact: ****@example.com, SSN: ***-**-*789"
      }
    ]
  }
}
```

Log output:

```text
[accessLog] PII detected in server response (masked in body): [{"pii_type": "Email", "masked_value": "****@example.com", "start": 14, "end": 34}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 41, "end": 52}]
```

When the action is set to **Reject**, the policy blocks the response, logs masked findings, and returns an HTTP 403 error:

Log output:

```text
[accessLog] PII detected in server response and declined: [{"pii_type": "Email", "masked_value": "****@example.com", "start": 14, "end": 34}, {"pii_type": "SSN", "masked_value": "***-**-*789", "start": 41, "end": 52}]
```

Error response:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "reason": "policy_pii_detected",
      "phase": "response",
      "policy": "mcp-pii-detector",
      "findings": [
        { "pii_type": "Email", "masked_value": "****@example.com" },
        { "pii_type": "SSN", "masked_value": "***-**-*789" }
      ]
    }
  }
}
```

The client does not receive the original response containing PII.

### [](#elicitation-response-example)Elicitation Response Example

When a client sends a JSON-RPC response back to the server (MCP elicitation pattern) containing PII, and the action is set to **Reject**, the policy rewrites the result:

Original elicitation response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "User SSN is 123-45-6789"
      }
    ]
  }
}
```

Sanitized response forwarded to server:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "decline",
    "reason": "Elicitation response declined due to detected PII"
  }
}
```

### [](#custom-pattern-example)Custom Pattern Example

This example shows detection of a custom AWS Access Key pattern in a request:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "deploy",
    "arguments": {
      "key": "AKIAIOSFODNN7EXAMPLE"
    }
  }
}
```

With a custom pattern configured (`name: AWS Access Key`, `pattern: AKIA[0-9A-Z]{16}`), the policy logs:

```text
[accessLog] PII detected in request (log only): [{"pii_type": "AWS Access Key", "value": "AKIAIOSFODNN7EXAMPLE", "start": 0, "end": 20}]
```

## [](#server-sent-events-sse-considerations)Server-Sent Events (SSE) Considerations

When the MCP server uses Server-Sent Events (text/event-stream) for streaming responses, the policy buffers and processes the entire stream:

- **Log**: The stream is forwarded unchanged with raw PII values logged.
- **Log and mask**: Each event’s result strings are rewritten with masked values while preserving SSE framing (event names, IDs, comments).
- **Reject**: The entire stream is replaced with a single JSON-RPC error envelope, and the Content-Type changes to application/json with HTTP 403 status.

<table><tbody><tr><td class="icon"><i class="fa icon-important" title="Important"></i></td><td class="content">SSE buffering is suitable for short-lived tool-call responses but might not be appropriate for long-lived server-pushed streams. For notification streams or progress updates, use the <strong>Log</strong> action to avoid buffering.</td></tr></tbody></table>

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">When <strong>Reject</strong> is applied to an SSE stream, the response Content-Type changes from text/event-stream to application/json. Clients that strictly require SSE formatting might need to handle this change.</td></tr></tbody></table>

## [](#compliance-and-data-flow)Compliance and Data Flow

This table shows where raw PII values appear based on the configured action:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 40%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Action</th>
<th class="tableblock halign-left valign-top">Request/Response Body on Wire</th>
<th class="tableblock halign-left valign-top">Access Log</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reject</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked (findings in error.data.findings[].masked_value)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Log and mask</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked (rewrites response body) or unchanged (forwards request unchanged)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Masked</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Log</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forwarded unchanged (raw PII flows through)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Raw</p></td>
</tr>
</tbody>
</table>

<table><tbody><tr><td class="icon"><i class="fa icon-important" title="Important"></i></td><td class="content"><strong>Reject</strong> is the strict mode that never writes raw PII values anywhere (wire or log). If you need raw values in logs for diagnostics, use the <strong>Log</strong> action instead.</td></tr></tbody></table>

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">For the A2A PII Detector policy, the <strong>Log and mask</strong> action only masks the access log, not the request body. The MCP PII Detector’s <strong>Log and mask</strong> action rewrites response bodies but forwards request bodies unchanged.</td></tr></tbody></table>

## [](#see-also)See Also

- [A2A PII Detector Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-pii-detector)
- [LLM PII Detection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-llm-pii-detection)

<!-- document id=4496ddaa0219348867b557e2325485008011a46a77d8cbe45b54eabbdcc256dd url=/mulesoft/current/en-us/gateway/1.12/policies-included-mcp-schema-validation.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Schema Validation policy validates that every incoming request complies with JsonRPC MCP
protocol.

When **Validate Tool Schema** is enabled, the policy also:

- Validates tool invocation request parameters against the JSON schema of the tool.

- Returns the tools/list MCP request without having to send the request to the upstream MCP Server.

When the policy can’t validate the request, it returns an
[MCP Error Response](https://modelcontextprotocol.io/specification/2025-11-25/basic#error-responses).

### Flex Gateway Local Mode

The MCP Schema Validation policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Validate Tool Schema</p></div></div></td><td><div><div><p>When enabled, the policy:</p></div><div><ul><li><p>Validates tool invocation request parameters against the JSON schema of the tool.</p></li><li><p>Returns the tools/list MCP request without having to send the request to the upstream MCP Server.</p></li></ul></div></div></td></tr></tbody></table>

<!-- document id=f773ffd68f1c330ecb67ba443327700dba80041bbe8d08afa266e7aff30309f9 url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-schema-validation.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-schema-validation-release-notes">MCP Schema Validation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Schema Validation policy validates that every incoming request complies with JsonRPC MCP
protocol.

When **Validate Tool Schema** is enabled, the policy also:

- Validates tool invocation request parameters against the JSON schema of the tool.

- Returns the tools/list MCP request without having to send the request to the upstream MCP Server.

When the policy can’t validate the request, it returns an
[MCP Error Response](https://modelcontextprotocol.io/specification/2025-11-25/basic#error-responses).

### Omni Gateway Local Mode

The MCP Schema Validation policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Validate Tool Schema</p></div></div></td><td><div><div><p>When enabled, the policy:</p></div><div><ul><li><p>Validates tool invocation request parameters against the JSON schema of the tool.</p></li><li><p>Returns the tools/list MCP request without having to send the request to the upstream MCP Server.</p></li></ul></div></div></td></tr><tr><td><div><div><p>Tool Poisoning Detection</p></div></div></td><td><div><div><p>Detects tool-poisoning attacks against MCP <code>tools/list</code> responses by pinning the trusted tool set from the API’s Anypoint Exchange asset and comparing every backend <code>tools/list</code> response against it. Here, the trusted asset is the cached Anypoint Exchange asset specification that the API is bound to, which is the same asset used to pin the trusted tool set. Detection runs against the backend response only when <strong>Validate Tool Schema</strong> is disabled. When <strong>Validate Tool Schema</strong> is enabled, <code>tools/list</code> is served from the trusted asset and detection is inactive. To learn more, see <a href="#tool-poisoning-detection">Configure Tool Poisoning Detection</a>.</p></div></div></td></tr></tbody></table>

### Configure Tool Poisoning Detection

Configure **Tool Poisoning Detection** to detect three types of tool-poisoning findings. Each
detection type is disabled by default.

For each detection type, configure an **Action** that determines how the policy handles the response
when it finds a poisoning attempt:

- `LogOnly`: Records the finding and leaves the response unchanged.

- `RemoveTool`: Removes only the affected tool from the response.

- `BlockResponse`: Replaces the entire `tools/list` response with a JSON-RPC error.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Descriptor Drift Detection</p></div></div></td><td><div><div><p>Detects when a pinned tool’s name, description, input schema, output schema, or annotations no longer match the pinned Exchange descriptor (a "rug pull"). This is the highest-confidence finding type. Configure <strong>Enabled</strong> to activate detection and <strong>Action</strong> to set the response handling.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Shadow Tool Name Detection</p></div></div></td><td><div><div><p>Detects tools that are present at runtime but absent from the pin, and flags those whose name is a near-twin of a pinned tool’s name as shadowing. Configure <strong>Enabled</strong> to activate detection and <strong>Action</strong> to set the response handling. Configure <strong>Max Edit Distance</strong> to set the maximum Levenshtein distance from a pinned tool name for an unpinned tool to be flagged as shadowing rather than merely unpinned. A value of <code>0</code> disables the shadowing annotation. The minimum value is <code>0</code> and the maximum value is <code>10</code>.</p></div></div></td><td><div><div><p>Disabled, <strong>Max Edit Distance</strong> <code>2</code></p></div></div></td></tr><tr><td><div><div><p>Prompt Injection Detection</p></div></div></td><td><div><div><p>Scans tool descriptor text fields for prompt-injection heuristics. Disabled by default because it is the lowest-confidence, highest-false-positive-risk finding type. Configure <strong>Enabled</strong> to activate detection and <strong>Action</strong> to set the response handling.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Max Tools Per Response</p></div></div></td><td><div><div><p>Sets the upper bound on how many tools in a single <code>tools/list</code> response the policy evaluates. Tools beyond this bound pass through unexamined, and the policy logs the truncation. The minimum value is <code>1</code>.</p></div></div></td><td><div><div><p><code>200</code></p></div></div></td></tr></tbody></table>

<!-- document id=b6a8f66913276597f5ae29e59d4ebb33d369cc6ea74a36dea473257004d7bef3 url=/mulesoft/current/en-us/gateway/1.9/policies-included-mcp-schema-validation.md -->

---
product: Omni Gateway
version: 1.9
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

## Summary

The MCP Schema Validation policy validates that every every JSON RPC request to the MCP server
complies with the MCP schema (MCP 2024\_11\_05 standard). If validation fails it will report a
Policy Violation.

There are no configuration parameters for this policy.

### Flex Gateway Local Mode

The MCP Schema Validation policy isn’t supported in Local Mode.

<!-- document id=64bc6c6a8ee9e6cc5d3d554b0be47ab324e2991263b4bbeff918e09e0e83a68b url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-schema-validation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-schema-validation-release-notes">MCP Schema Validation</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Schema Validation policy validates that every incoming request complies with JsonRPC MCP
protocol.

When **Validate Tool Schema** is enabled, the policy also:

- Validates tool invocation request parameters against the JSON schema of the tool.

- Returns the tools/list MCP request without having to send the request to the upstream MCP Server.

When the policy can’t validate the request, it returns an
[MCP Error Response](https://modelcontextprotocol.io/specification/2025-11-25/basic#error-responses).

### Omni Gateway Local Mode

The MCP Schema Validation policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Validate Tool Schema</p></div></div></td><td><div><div><p>When enabled, the policy:</p></div><div><ul><li><p>Validates tool invocation request parameters against the JSON schema of the tool.</p></li><li><p>Returns the tools/list MCP request without having to send the request to the upstream MCP Server.</p></li></ul></div></div></td></tr><tr><td><div><div><p>Tool Poisoning Detection</p></div></div></td><td><div><div><p>Detects tool-poisoning attacks against MCP <code>tools/list</code> responses by pinning the trusted tool set from the API’s Anypoint Exchange asset and comparing every backend <code>tools/list</code> response against it. Here, the trusted asset is the cached Anypoint Exchange asset specification that the API is bound to, which is the same asset used to pin the trusted tool set. Detection runs against the backend response only when <strong>Validate Tool Schema</strong> is disabled. When <strong>Validate Tool Schema</strong> is enabled, <code>tools/list</code> is served from the trusted asset and detection is inactive. To learn more, see <a href="#tool-poisoning-detection">Configure Tool Poisoning Detection</a>.</p></div></div></td></tr></tbody></table>

### Configure Tool Poisoning Detection

Configure **Tool Poisoning Detection** to detect three types of tool-poisoning findings. Each
detection type is disabled by default.

For each detection type, configure an **Action** that determines how the policy handles the response
when it finds a poisoning attempt:

- `LogOnly`: Records the finding and leaves the response unchanged.

- `RemoveTool`: Removes only the affected tool from the response.

- `BlockResponse`: Replaces the entire `tools/list` response with a JSON-RPC error.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Descriptor Drift Detection</p></div></div></td><td><div><div><p>Detects when a pinned tool’s name, description, input schema, output schema, or annotations no longer match the pinned Exchange descriptor (a "rug pull"). This is the highest-confidence finding type. Configure <strong>Enabled</strong> to activate detection and <strong>Action</strong> to set the response handling.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Shadow Tool Name Detection</p></div></div></td><td><div><div><p>Detects tools that are present at runtime but absent from the pin, and flags those whose name is a near-twin of a pinned tool’s name as shadowing. Configure <strong>Enabled</strong> to activate detection and <strong>Action</strong> to set the response handling. Configure <strong>Max Edit Distance</strong> to set the maximum Levenshtein distance from a pinned tool name for an unpinned tool to be flagged as shadowing rather than merely unpinned. A value of <code>0</code> disables the shadowing annotation. The minimum value is <code>0</code> and the maximum value is <code>10</code>.</p></div></div></td><td><div><div><p>Disabled, <strong>Max Edit Distance</strong> <code>2</code></p></div></div></td></tr><tr><td><div><div><p>Prompt Injection Detection</p></div></div></td><td><div><div><p>Scans tool descriptor text fields for prompt-injection heuristics. Disabled by default because it is the lowest-confidence, highest-false-positive-risk finding type. Configure <strong>Enabled</strong> to activate detection and <strong>Action</strong> to set the response handling.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Max Tools Per Response</p></div></div></td><td><div><div><p>Sets the upper bound on how many tools in a single <code>tools/list</code> response the policy evaluates. Tools beyond this bound pass through unexamined, and the policy logs the truncation. The minimum value is <code>1</code>.</p></div></div></td><td><div><div><p><code>200</code></p></div></div></td></tr></tbody></table>

<!-- document id=a63c3708458665a27733ba729e1c67f1aafb7f1b7ac8601edc701497ea7f152a url=/mulesoft/current/en-us/gateway/1.12/policies-included-mcp-support.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Support Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Support</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds MCP support to a Flex Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Support Policy configures Flex Gateway to support MCP server instances. You must apply this
policy to all MCP server instances for the instance to function properly. If you don’t apply this
policy, Flex Gateway might throw a runtime error.

The MCP Support policy enables the **Total MCP Calls** metric that tracks the total successful and
unsuccessful calls made to the MCP server. To view the total MCP calls, see
[Viewing Key Metrics in API Manager for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-api-metrics).

There are no configuration parameters for this policy.

> [!NOTE] This policy must come first in policy order. If this policy doesn’t come first, Flex
> Gateway might throw a runtime error.

### Flex Gateway Local Mode

The MCP Support policy isn’t supported in Local Mode.

<!-- document id=5db9904fa233eee29d1dc42a6bcba4be61af5ac6e79508075e68c80288a63804 url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-support.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Support Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Support</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds MCP support to an Omni Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-support-release-notes">MCP Support</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Support Policy configures Omni Gateway to support MCP server instances. You must apply this
policy to all MCP server instances for the instance to function properly. If you don’t apply this
policy, Omni Gateway might throw a runtime error.

The MCP Support policy enables the **Total MCP Calls** metric that tracks the total successful and
unsuccessful calls made to the MCP server. To view the total MCP calls, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-view-api-metrics).

Configure the policy to inject the MCP primitive as request headers toward the upstream backend so
that downstream policies can use it. To learn more, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] This policy must come first in policy order. If this policy doesn’t come first, Omni
> Gateway might throw a runtime error.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Support policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Inject MCP Element Headers</p></div></div></td><td><div><div><p>Injects the MCP primitive as request headers for downstream policy use. The policy sets <code>x-ms-mcp-element-id</code> to the identifier (<code>tools/call</code> name, <code>prompts/get</code> name, or <code>resources/read</code> URI) and <code>x-ms-mcp-element-type</code> to the kind (<code>tool</code>, <code>prompt</code>, or <code>resource</code>). These headers lets a downstream policy match on type, an individual element or both</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr></tbody></table>

<!-- document id=fe3a4f470c62eae80a06d20399d1dda242c5d16f2407c88276d122c096657fa7 url=/mulesoft/current/en-us/gateway/1.9/policies-included-mcp-support.md -->

---
product: Omni Gateway
version: 1.9
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Support Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Support</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds MCP support to a Flex Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The MCP Support Policy configures Flex Gateway to support MCP server instances. You must apply this
policy to all MCP server instances for the instance to function properly. If you don’t apply this
policy, Flex Gateway might throw a runtime error.

There are no configuration parameters for this policy.

> [!NOTE] This policy must come first in policy order. If this policy doesn’t come first, Flex
> Gateway might throw a runtime error.

### Flex Gateway Local Mode

The MCP Support policy isn’t supported in Local Mode.

<!-- document id=5f4f62d62c0bd6f1f5492b0d530634c90951fc4b4d192b960940757b8a0b96a3 url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-support.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# MCP Support Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Support</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Adds MCP support to an Omni Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.3</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-support-release-notes">MCP Support</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Support Policy configures Omni Gateway to support MCP server instances. You must apply this
policy to all MCP server instances for the instance to function properly. If you don’t apply this
policy, Omni Gateway might throw a runtime error.

The MCP Support policy enables the **Total MCP Calls** metric that tracks the total successful and
unsuccessful calls made to the MCP server. To view the total MCP calls, see
[Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-view-api-metrics).

Configure the policy to inject the MCP primitive as request headers toward the upstream backend so
that downstream policies can use it. To learn more, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] This policy must come first in policy order. If this policy doesn’t come first, Omni
> Gateway might throw a runtime error.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Support policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Inject MCP Element Headers</p></div></div></td><td><div><div><p>Injects the MCP primitive as request headers for downstream policy use. The policy sets <code>x-ms-mcp-element-id</code> to the identifier (<code>tools/call</code> name, <code>prompts/get</code> name, or <code>resources/read</code> URI) and <code>x-ms-mcp-element-type</code> to the kind (<code>tool</code>, <code>prompt</code>, or <code>resource</code>). These headers lets a downstream policy match on type, an individual element or both</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr></tbody></table>

<!-- document id=8bc60936e99b990c439be6db76975918cf2bc467e86ed25b0bc0deae8b374ee7 url=/mulesoft/current/en-us/gateway/1.12/policies-included-mcp-tool-mapping.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, mcp, tool mapping
---

# MCP Tool Mapping Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Tool Mapping</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Tool Mapping policy intercepts MCP protocol traffic and applies configurable name
transformations to tools.

With this policy, you can:

- Rename tools for readability

- Rename tools for consistency across different MCP servers

- Add prefixes or suffixes to tool names for namespacing

- Create pattern-based transformations by using regex

- Create custom descriptions for mapped tools

The MCP Tool Mapping policy supports both outbound mapping (transforming tool names in `tools/list`
responses from backend to client) and inbound mapping (reverse-transforming tool names in
`tools/call` requests from client to backend). The policy automatically maintains bidirectional
mapping, ensuring that tool names are correctly transformed in both directions to maintain
consistency between client and backend.

The policy works with both MCP transport types:

- Standard JSON over HTTP: Transforms tool names in JSON-RPC messages

- Server-Sent Events (SSE): Transforms tool names in SSE streaming responses

## Configuring Policy Parameters

### Flex Gateway Local Mode

The MCP Tool Mapping policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Tool Name Mappings</p></div></div></td><td><div><div><p>Defines the tool name mappings. Each mapping specifies how to transform tool names between the client and backend.</p></div></div></td></tr><tr><td><div><div><p>Source Tool Name</p></div></div></td><td><div><div><p>Defines the original tool name from the MCP server or a regex pattern for pattern-based matching with capture group replacement.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Name</p></div></div></td><td><div><div><p>Defines the new tool name to use in responses. For regex mappings, use <code>$1</code>, <code>$2</code>, <code>$3</code>, and so on to reference capture groups.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Description</p></div></div></td><td><div><div><p>Optional new description for the tool. If not specified, the original description is used. New descriptions aren’t supported for regex mappings.</p></div></div></td></tr><tr><td><div><div><p>Mapping Type</p></div></div></td><td><div><div><p>Determines how the tool mapping is processed. Supported values are <strong>Literal</strong> for exact string matching and <strong>Regex</strong> for pattern matching with capture groups.</p></div></div></td></tr><tr><td><div><div><p>Log Mappings</p></div></div></td><td><div><div><p>Logs tool names and mappings for debugging if enabled. For example:</p></div><div><div><pre>Mapped outbound tool (literal): get_me -&gt; ss_get_me
Passthrough outbound tool (no mapping): get_release_by_tag</pre></div></div></div></td></tr></tbody></table>

## Mapping Types

The MCP Tool Mapping policy supports literal mapping for exact string matching and regex mapping for
pattern-based matching with capture group replacement.

### Literal Mapping

Literal mappings perform exact string matching for specific tool names. For example, given the
following parameters:

- **Source Tool Name**: `get_weather`

- **Mapped Tool Name**: `weather_lookup`

- **Mapped Tool Description**: `Get current weather conditions`

- **Mapping Type**: **Literal**

The policy transforms the tool name in the `tools/list` response and `tools/call` request:

- `tools/list` response: `get_weather` to `weather_lookup`

- `tools/call` request: `weather_lookup` to `get_weather` (automatic reverse mapping)

### Regex Mapping

Regex mappings use pattern-based matching with capture group replacement. For example, given the
following parameters:

- **Source Tool Name**: `get_(.+)`

- **Mapped Tool Name**: `fetch_$1`

- **Mapping Type**: **Regex**

The policy transforms the tool name in the `tools/list` response:

- `get_weather` to `fetch_weather`

- `get_user` to `fetch_user`

- `delete_item` remains unchanged (doesn’t match pattern)

## Bidirectional Mapping

For outbound `tools/list` mapping response, the policy transforms tool names when the backend MCP
server returns a list of available tools:

1.  Backend MCP server returns tools: `["get_weather", "get_user", "delete_item"]`

2.  Policy applies mappings:

    - `get_weather` to `weather_lookup` (literal match)

    - `get_user` to `user_info` (literal match)

    - `delete_item` remains unchanged (no mapping)

3.  Client receives: `["weather_lookup", "user_info", "delete_item"]`

For inbound `tools/call` mapping requests, the policy transforms tool names when the client calls a
tool:

The policy reverse-transforms tool names when the client calls a tool:

1.  Client calls: `weather_lookup` (the mapped name)

2.  Policy reverse-maps: `weather_lookup` to `get_weather`

3.  Backend receives: `get_weather` (original name)

## Namespace Isolation Use Case

Add prefixes to avoid tool name conflicts between multiple MCP servers. For example, this
configuration adds the prefix `server1_` to all tool names:

- **Source Tool Name**: `(.+)`

- **Mapped Tool Name**: `server1_$1`

- **Mapping Type**: `regex`

## Consistent Naming Use Case

Standardize tool names across different servers. For example, this configuration standardizes the
name of `fetch` and `retrieve` functions from different servers to `get` functions:

- Mapping 1:

  - **Source Tool Name**: `fetchWeather`

  - **Mapped Tool Name**: `get_weather`

  - **Mapping Type**: `literal`

- Mapping 2:

  - **Source Tool Name**: `retrieveUser`

  - **Mapped Tool Name**: `get_user`

  - **Mapping Type**: `literal`

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/1.12/policies-mcp-access-control-together)

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-global-access)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.12/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory)

<!-- document id=45c82cda8ecf31d37ca7dc6a62b469e5b690a58bdb7ef68209246f5918e88f1f url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-tool-mapping.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, mcp, tool mapping
---

# MCP Tool Mapping Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Tool Mapping</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-tool-mapping-release-notes">MCP Tool Mapping</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Tool Mapping policy intercepts MCP protocol traffic and applies configurable name
transformations to tools.

With this policy, you can:

- Rename tools for readability

- Rename tools for consistency across different MCP servers

- Add prefixes or suffixes to tool names for namespacing

- Create pattern-based transformations by using regex

- Create custom descriptions for mapped tools

The MCP Tool Mapping policy supports both outbound mapping (transforming tool names in `tools/list`
responses from backend to client) and inbound mapping (reverse-transforming tool names in
`tools/call` requests from client to backend). The policy automatically maintains bidirectional
mapping, ensuring that tool names are correctly transformed in both directions to maintain
consistency between client and backend.

The policy works with both MCP transport types:

- Standard JSON over HTTP: Transforms tool names in JSON-RPC messages

- Server-Sent Events (SSE): Transforms tool names in SSE streaming responses

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Tool Mapping policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Tool Name Mappings</p></div></div></td><td><div><div><p>Defines the tool name mappings. Each mapping specifies how to transform tool names between the client and backend.</p></div></div></td></tr><tr><td><div><div><p>Source Tool Name</p></div></div></td><td><div><div><p>Defines the original tool name from the MCP server or a regex pattern for pattern-based matching with capture group replacement.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Name</p></div></div></td><td><div><div><p>Defines the new tool name to use in responses. For regex mappings, use <code>$1</code>, <code>$2</code>, <code>$3</code>, and so on to reference capture groups.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Description</p></div></div></td><td><div><div><p>Optional new description for the tool. If not specified, the original description is used. New descriptions aren’t supported for regex mappings.</p></div></div></td></tr><tr><td><div><div><p>Mapping Type</p></div></div></td><td><div><div><p>Determines how the tool mapping is processed. Supported values are <strong>Literal</strong> for exact string matching and <strong>Regex</strong> for pattern matching with capture groups.</p></div></div></td></tr><tr><td><div><div><p>Log Mappings</p></div></div></td><td><div><div><p>Logs tool names and mappings for debugging if enabled. For example:</p></div><div><div><pre>Mapped outbound tool (literal): get_me -&gt; ss_get_me
Passthrough outbound tool (no mapping): get_release_by_tag</pre></div></div></div></td></tr></tbody></table>

## Mapping Types

The MCP Tool Mapping policy supports literal mapping for exact string matching and regex mapping for
pattern-based matching with capture group replacement.

### Literal Mapping

Literal mappings perform exact string matching for specific tool names. For example, given the
following parameters:

- **Source Tool Name**: `get_weather`

- **Mapped Tool Name**: `weather_lookup`

- **Mapped Tool Description**: `Get current weather conditions`

- **Mapping Type**: **Literal**

The policy transforms the tool name in the `tools/list` response and `tools/call` request:

- `tools/list` response: `get_weather` to `weather_lookup`

- `tools/call` request: `weather_lookup` to `get_weather` (automatic reverse mapping)

### Regex Mapping

Regex mappings use pattern-based matching with capture group replacement. For example, given the
following parameters:

- **Source Tool Name**: `get_(.+)`

- **Mapped Tool Name**: `fetch_$1`

- **Mapping Type**: **Regex**

The policy transforms the tool name in the `tools/list` response:

- `get_weather` to `fetch_weather`

- `get_user` to `fetch_user`

- `delete_item` remains unchanged (doesn’t match pattern)

## Bidirectional Mapping

For outbound `tools/list` mapping response, the policy transforms tool names when the backend MCP
server returns a list of available tools:

1.  Backend MCP server returns tools: `["get_weather", "get_user", "delete_item"]`

2.  Policy applies mappings:

    - `get_weather` to `weather_lookup` (literal match)

    - `get_user` to `user_info` (literal match)

    - `delete_item` remains unchanged (no mapping)

3.  Client receives: `["weather_lookup", "user_info", "delete_item"]`

For inbound `tools/call` mapping requests, the policy transforms tool names when the client calls a
tool:

The policy reverse-transforms tool names when the client calls a tool:

1.  Client calls: `weather_lookup` (the mapped name)

2.  Policy reverse-maps: `weather_lookup` to `get_weather`

3.  Backend receives: `get_weather` (original name)

## Namespace Isolation Use Case

Add prefixes to avoid tool name conflicts between multiple MCP servers. For example, this
configuration adds the prefix `server1_` to all tool names:

- **Source Tool Name**: `(.+)`

- **Mapped Tool Name**: `server1_$1`

- **Mapping Type**: `regex`

## Consistent Naming Use Case

Standardize tool names across different servers. For example, this configuration standardizes the
name of `fetch` and `retrieve` functions from different servers to `get` functions:

- Mapping 1:

  - **Source Tool Name**: `fetchWeather`

  - **Mapped Tool Name**: `get_weather`

  - **Mapping Type**: `literal`

- Mapping 2:

  - **Source Tool Name**: `retrieveUser`

  - **Mapped Tool Name**: `get_user`

  - **Mapping Type**: `literal`

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/1.13/policies-mcp-access-control-together)

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-global-access)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

<!-- document id=9948d73e0ffed2168bcb9b595cb7e3cdd0fc532cc5e6b7467095f79c5536a152 url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-tool-mapping.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, mcp, tool mapping
---

# MCP Tool Mapping Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Tool Mapping</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-tool-mapping-release-notes">MCP Tool Mapping</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Tool Mapping policy intercepts MCP protocol traffic and applies configurable name
transformations to tools.

With this policy, you can:

- Rename tools for readability

- Rename tools for consistency across different MCP servers

- Add prefixes or suffixes to tool names for namespacing

- Create pattern-based transformations by using regex

- Create custom descriptions for mapped tools

The MCP Tool Mapping policy supports both outbound mapping (transforming tool names in `tools/list`
responses from backend to client) and inbound mapping (reverse-transforming tool names in
`tools/call` requests from client to backend). The policy automatically maintains bidirectional
mapping, ensuring that tool names are correctly transformed in both directions to maintain
consistency between client and backend.

The policy works with both MCP transport types:

- Standard JSON over HTTP: Transforms tool names in JSON-RPC messages

- Server-Sent Events (SSE): Transforms tool names in SSE streaming responses

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Tool Mapping policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Element</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Tool Name Mappings</p></div></div></td><td><div><div><p>Defines the tool name mappings. Each mapping specifies how to transform tool names between the client and backend.</p></div></div></td></tr><tr><td><div><div><p>Source Tool Name</p></div></div></td><td><div><div><p>Defines the original tool name from the MCP server or a regex pattern for pattern-based matching with capture group replacement.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Name</p></div></div></td><td><div><div><p>Defines the new tool name to use in responses. For regex mappings, use <code>$1</code>, <code>$2</code>, <code>$3</code>, and so on to reference capture groups.</p></div></div></td></tr><tr><td><div><div><p>Mapped Tool Description</p></div></div></td><td><div><div><p>Optional new description for the tool. If not specified, the original description is used. New descriptions aren’t supported for regex mappings.</p></div></div></td></tr><tr><td><div><div><p>Mapping Type</p></div></div></td><td><div><div><p>Determines how the tool mapping is processed. Supported values are <strong>Literal</strong> for exact string matching and <strong>Regex</strong> for pattern matching with capture groups.</p></div></div></td></tr><tr><td><div><div><p>Log Mappings</p></div></div></td><td><div><div><p>Logs tool names and mappings for debugging if enabled. For example:</p></div><div><div><pre>Mapped outbound tool (literal): get_me -&gt; ss_get_me
Passthrough outbound tool (no mapping): get_release_by_tag</pre></div></div></div></td></tr></tbody></table>

## Mapping Types

The MCP Tool Mapping policy supports literal mapping for exact string matching and regex mapping for
pattern-based matching with capture group replacement.

### Literal Mapping

Literal mappings perform exact string matching for specific tool names. For example, given the
following parameters:

- **Source Tool Name**: `get_weather`

- **Mapped Tool Name**: `weather_lookup`

- **Mapped Tool Description**: `Get current weather conditions`

- **Mapping Type**: **Literal**

The policy transforms the tool name in the `tools/list` response and `tools/call` request:

- `tools/list` response: `get_weather` to `weather_lookup`

- `tools/call` request: `weather_lookup` to `get_weather` (automatic reverse mapping)

### Regex Mapping

Regex mappings use pattern-based matching with capture group replacement. For example, given the
following parameters:

- **Source Tool Name**: `get_(.+)`

- **Mapped Tool Name**: `fetch_$1`

- **Mapping Type**: **Regex**

The policy transforms the tool name in the `tools/list` response:

- `get_weather` to `fetch_weather`

- `get_user` to `fetch_user`

- `delete_item` remains unchanged (doesn’t match pattern)

## Bidirectional Mapping

For outbound `tools/list` mapping response, the policy transforms tool names when the backend MCP
server returns a list of available tools:

1.  Backend MCP server returns tools: `["get_weather", "get_user", "delete_item"]`

2.  Policy applies mappings:

    - `get_weather` to `weather_lookup` (literal match)

    - `get_user` to `user_info` (literal match)

    - `delete_item` remains unchanged (no mapping)

3.  Client receives: `["weather_lookup", "user_info", "delete_item"]`

For inbound `tools/call` mapping requests, the policy transforms tool names when the client calls a
tool:

The policy reverse-transforms tool names when the client calls a tool:

1.  Client calls: `weather_lookup` (the mapped name)

2.  Policy reverse-maps: `weather_lookup` to `get_weather`

3.  Backend receives: `get_weather` (original name)

## Namespace Isolation Use Case

Add prefixes to avoid tool name conflicts between multiple MCP servers. For example, this
configuration adds the prefix `server1_` to all tool names:

- **Source Tool Name**: `(.+)`

- **Mapped Tool Name**: `server1_$1`

- **Mapping Type**: `regex`

## Consistent Naming Use Case

Standardize tool names across different servers. For example, this configuration standardizes the
name of `fetch` and `retrieve` functions from different servers to `get` functions:

- Mapping 1:

  - **Source Tool Name**: `fetchWeather`

  - **Mapped Tool Name**: `get_weather`

  - **Mapping Type**: `literal`

- Mapping 2:

  - **Source Tool Name**: `retrieveUser`

  - **Mapped Tool Name**: `get_user`

  - **Mapping Type**: `literal`

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together)

- [MCP Global Access](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

<!-- document id=ebb14dc3a6398acc33c60a67ac3c556810dfb8af41cc9d799248c30b77af4b21 url=/mulesoft/current/en-us/gateway/1.13/policies-included-mcp-progressive-disclosure.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, mcp, progressive disclosure, tool search
---

# MCP Tools Progressive Disclosure Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Tools Progressive Disclosure</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Reduces context window token cost by exposing tools on-demand through search</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-progressive-disclosure-release-notes">MCP Tools Progressive Disclosure</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Tools Progressive Disclosure policy reduces an MCP client’s context-window token cost by
hiding the `tools/list` catalog behind these tools:

- **`search_tools`**: Finds relevant tools on demand by matching a query against tool names and
  descriptions.

- **`invoke_tool`**: Calls a tool discovered via `search_tools`.

With this policy, you can:

- Reduce token consumption by exposing tools on-demand rather than listing all tools up front.

- Keep frequently-used tools immediately available through `hotTools` configuration.

- Support paginated search results for large tool catalogs.

- Preserve normal tool invocation semantics for upstream policies.

> [!IMPORTANT] This policy must be positioned after the
> [MCP Support Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-support) but before any other MCP authorization
> policies, such as [access control](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control),
> [tool mapping](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping), or
> [schema validation](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-schema-validation) policies. To learn more about MCP
> authorization policies, see
> [Configuring MCP Access Control Policies](https://docs.mulesoft.com/gateway/1.13/policies-mcp-access-control-together).

The policy performs no tool caching. Every `tools/list`, `search_tools`, and `invoke_tool` request
is resolved against the live upstream, so the client always sees the real, per-caller-filtered
upstream state.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Tools Progressive Disclosure policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Search Result Limit</p></div></div></td><td><div><div><p>The maximum number of matches a <code>search_tools</code> query returns per page when the query omits its own <code>limit</code> parameter.</p></div></div></td><td><div><div><p><code>20</code></p></div></div></td></tr><tr><td><div><div><p>Hot Tools</p></div></div></td><td><div><div><p>Tool names or patterns that bypass disclosure. Matched tools appear in the client-facing <code>tools/list</code> with their original upstream schemas.</p></div></div></td><td><div><div><p><code>[]</code> (empty)</p></div></div></td></tr><tr><td><div><div><p>Meta Tool Prefix</p></div></div></td><td><div><div><p>A prefix prepended to the <code>search_tools</code> and <code>invoke_tool</code> meta-tool names to avoid namespace collisions with upstream tool names. The prefix is concatenated directly with no separator added (such as <code>_</code>) in the prefix value itself.</p></div></div></td><td><div><div><p><code>""</code> (empty)</p></div></div></td></tr></tbody></table>

### Configuration Example

```yaml
- policyRef:
    name: mcp-tools-progressive-disclosure-policy-flex
  config:
    searchResultLimit: 20
    hotTools:
      - "get_weather"
      - "list_*"
    metaToolPrefix: "mcp_"
```

> [!NOTE] The `metaToolPrefix` value `"mcp_"` produces `mcp_search_tools` and `mcp_invoke_tool`. The
> underscore is part of the configured prefix, not added automatically.

## How It Works

### Meta-Tool Advertisement

When a client requests `tools/list`, the policy:

1.  Forwards the request upstream to get the live, per-caller-filtered tool catalog.

2.  Replaces the full catalog with the two meta-tools (`search_tools` and `invoke_tool`).

3.  Includes any tools matching the configured `hotTools` patterns with their original schemas.

### Tool Discovery

When a client calls `search_tools`:

1.  The policy forwards a synthesized `tools/list` request upstream.

2.  The upstream [access control policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control) filters the
    list per caller.

3.  The policy runs the search query against the filtered list.

4.  Matching tools are returned with their full schemas, sufficient to construct an `invoke_tool`
    call.

### Tool Invocation

When a client calls `invoke_tool`:

1.  The policy rewrites the request as a native `tools/call` with the wrapped tool name.

2.  All upstream policies see the real tool name (not `invoke_tool`).

3.  The response is returned to the caller unchanged.

This normalization ensures that access control, tool mapping, and other policies operate on the real
tool name without progressive-disclosure awareness.

## Hot Tools Configuration

The `hotTools` configuration enables you to keep frequently-used tools immediately visible without
requiring a search. Tools matching the patterns appear in `tools/list` alongside `search_tools` and
`invoke_tool`.

### Pattern Matching

- Use exact names: `"get_weather"`.

- Use glob patterns: `"list_*"`, `"*_info"`.

- Matches are evaluated against the live upstream `tools/list` response on every request.

- Only tools the caller is authorized to see (per the chain’s
  [access control policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control)) will match.

### Use Cases

**Frequently-used tools**: Keep high-traffic tools immediately available to reduce search
round-trips.

```yaml
hotTools:
  - "get_weather"
  - "get_user"
```

**Namespace patterns**: Expose all tools from a specific namespace.

```yaml
hotTools:
  - "weather_*"
  - "user_*"
```

## Search Tool Usage

The `search_tools` meta-tool accepts a JSON object with the following parameters:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>query</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>A case-insensitive regular expression to match against tool names and descriptions. Separate alternative keywords with <code>|</code> (spaces match literally).</p></div></div></td></tr><tr><td><div><div><p><code>limit</code></p></div></div></td><td><div><div><p>integer</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum number of results to return per page. If omitted, uses the configured <code>searchResultLimit</code>.</p></div></div></td></tr><tr><td><div><div><p><code>cursor</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Opaque pagination cursor from a prior search’s <code>nextCursor</code> field. Pass it back to fetch the next page.</p></div></div></td></tr></tbody></table>

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "query": "weather",
      "limit": 3
    }
  }
}
```

### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 1 matching tool(s)."
      }
    ],
    "structuredContent": {
      "matches": [
        {
          "name": "get_weather",
          "description": "Return the current weather for a city",
          "inputSchema": {
            "type": "object",
            "required": ["city"],
            "properties": {
              "city": {
                "type": "string"
              }
            }
          }
        }
      ]
    }
  }
}
```

### Pagination

When more tools match than fit on a page, the response includes a `nextCursor` field under
`structuredContent`:

```json
{
  "structuredContent": {
    "matches": [...],
    "nextCursor": "eyJxIjoid2VhdGhlciIsIm8iOjIwfQ=="
  }
}
```

To fetch the next page, pass the cursor back in the `arguments`:

```json
{
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "cursor": "eyJxIjoid2VhdGhlciIsIm8iOjIwfQ=="
    }
  }
}
```

Each page resolves against a fresh upstream `tools/list`, ensuring the correct authorization. The
`query` parameter may be omitted when using a cursor (the cursor carries it).

## Invoke Tool Usage

The `invoke_tool` meta-tool wraps a call to a discovered tool. It accepts:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>name</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The tool name returned from <code>search_tools</code></p></div></div></td></tr><tr><td><div><div><p><code>arguments</code></p></div></div></td><td><div><div><p>object</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The tool’s input parameters as returned in the <code>inputSchema</code> from <code>search_tools</code></p></div></div></td></tr></tbody></table>

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "invoke_tool",
    "arguments": {
      "name": "get_weather",
      "arguments": {
        "city": "San Francisco"
      }
    }
  }
}
```

The policy rewrites this as a native `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "San Francisco"
    }
  }
}
```

All upstream policies see `get_weather` (not `invoke_tool`), ensuring access control, tool mapping,
and other policies operate correctly.

## Filter Chain Ordering

The MCP Tools Progressive Disclosure policy must be positioned after the
[MCP Support Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-support) but before any other MCP policies in the filter
chain, particularly before any policy that reads tool names (access control, tool mapping, schema
validation).

If positioned after an access control policy, that policy would see `invoke_tool` (the meta-tool) in
the request and gate the envelope—not the real tool inside—creating an authorization bypass.

## Delegated Authorization

The policy maintains per-caller authorization parity by delegating to the chain:

1.  A `search_tools` call triggers a synthesized `tools/list` request upstream.

2.  The upstream [access control policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control) filters the
    list per caller.

3.  The policy runs the query against the filtered list.

4.  Only tools the caller is authorized to see are included in results.

This ensures:

- Callers don’t see tools they cannot invoke.

- Results reflect live authorization state.

- No caching of authorization decisions.

If no [access control policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control) is present,
`search_tools` returns the full unfiltered catalog—the same as a direct `tools/list` would in that
chain.

## Error Responses

The policy returns JSON-RPC error objects with a stable `data.reason` field for machine-checkable
error handling.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Case</th><th>Code</th><th><code>data.reason</code></th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Malformed <code>invoke_tool</code></p></div></div></td><td><div><div><p><code>-32602</code></p></div></div></td><td><div><div><p><code>invalid_params</code></p></div></div></td><td><div><div><p>Missing or invalid <code>arguments.name</code> or <code>arguments.arguments</code></p></div></div></td></tr><tr><td><div><div><p>Malformed <code>search_tools</code></p></div></div></td><td><div><div><p><code>-32602</code></p></div></div></td><td><div><div><p><code>invalid_params</code></p></div></div></td><td><div><div><p>Empty/missing/non-string query, exceeds 256 characters, invalid regex, bad <code>limit</code>, missing <code>id</code>, malformed <code>cursor</code>, or <code>cursor</code>/<code>query</code> mismatch</p></div></div></td></tr></tbody></table>

Errors produced upstream (access control denials, upstream tool errors) pass through unchanged.

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/1.13/policies-mcp-access-control-together)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping)

- [MCP Global Access](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-global-access)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

<!-- document id=9f538f6eb0b0d93559aa41222f52e8eb12717364f6acdd2eb72c1a78f21fb36d url=/mulesoft/current/en-us/gateway/latest/policies-included-mcp-progressive-disclosure.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, mcp, progressive disclosure, tool search
---

# MCP Tools Progressive Disclosure Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Tools Progressive Disclosure</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Reduces context window token cost by exposing tools on-demand through search</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-progressive-disclosure-release-notes">MCP Tools Progressive Disclosure</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Tools Progressive Disclosure policy reduces an MCP client’s context-window token cost by
hiding the `tools/list` catalog behind these tools:

- **`search_tools`**: Finds relevant tools on demand by matching a query against tool names and
  descriptions.

- **`invoke_tool`**: Calls a tool discovered via `search_tools`.

With this policy, you can:

- Reduce token consumption by exposing tools on-demand rather than listing all tools up front.

- Keep frequently-used tools immediately available through `hotTools` configuration.

- Support paginated search results for large tool catalogs.

- Preserve normal tool invocation semantics for upstream policies.

> [!IMPORTANT] This policy must be positioned after the
> [MCP Support Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support) but before any other MCP authorization
> policies, such as [access control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control),
> [tool mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping), or
> [schema validation](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-schema-validation) policies. To learn more about MCP
> authorization policies, see
> [Configuring MCP Access Control Policies](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together).

The policy performs no tool caching. Every `tools/list`, `search_tools`, and `invoke_tool` request
is resolved against the live upstream, so the client always sees the real, per-caller-filtered
upstream state.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Tools Progressive Disclosure policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Search Result Limit</p></div></div></td><td><div><div><p>The maximum number of matches a <code>search_tools</code> query returns per page when the query omits its own <code>limit</code> parameter.</p></div></div></td><td><div><div><p><code>20</code></p></div></div></td></tr><tr><td><div><div><p>Hot Tools</p></div></div></td><td><div><div><p>Tool names or patterns that bypass disclosure. Matched tools appear in the client-facing <code>tools/list</code> with their original upstream schemas.</p></div></div></td><td><div><div><p><code>[]</code> (empty)</p></div></div></td></tr><tr><td><div><div><p>Meta Tool Prefix</p></div></div></td><td><div><div><p>A prefix prepended to the <code>search_tools</code> and <code>invoke_tool</code> meta-tool names to avoid namespace collisions with upstream tool names. The prefix is concatenated directly with no separator added (such as <code>_</code>) in the prefix value itself.</p></div></div></td><td><div><div><p><code>""</code> (empty)</p></div></div></td></tr></tbody></table>

### Configuration Example

```yaml
- policyRef:
    name: mcp-tools-progressive-disclosure-policy-flex
  config:
    searchResultLimit: 20
    hotTools:
      - "get_weather"
      - "list_*"
    metaToolPrefix: "mcp_"
```

> [!NOTE] The `metaToolPrefix` value `"mcp_"` produces `mcp_search_tools` and `mcp_invoke_tool`. The
> underscore is part of the configured prefix, not added automatically.

## How It Works

### Meta-Tool Advertisement

When a client requests `tools/list`, the policy:

1.  Forwards the request upstream to get the live, per-caller-filtered tool catalog.

2.  Replaces the full catalog with the two meta-tools (`search_tools` and `invoke_tool`).

3.  Includes any tools matching the configured `hotTools` patterns with their original schemas.

### Tool Discovery

When a client calls `search_tools`:

1.  The policy forwards a synthesized `tools/list` request upstream.

2.  The upstream [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control) filters the
    list per caller.

3.  The policy runs the search query against the filtered list.

4.  Matching tools are returned with their full schemas, sufficient to construct an `invoke_tool`
    call.

### Tool Invocation

When a client calls `invoke_tool`:

1.  The policy rewrites the request as a native `tools/call` with the wrapped tool name.

2.  All upstream policies see the real tool name (not `invoke_tool`).

3.  The response is returned to the caller unchanged.

This normalization ensures that access control, tool mapping, and other policies operate on the real
tool name without progressive-disclosure awareness.

## Hot Tools Configuration

The `hotTools` configuration enables you to keep frequently-used tools immediately visible without
requiring a search. Tools matching the patterns appear in `tools/list` alongside `search_tools` and
`invoke_tool`.

### Pattern Matching

- Use exact names: `"get_weather"`.

- Use glob patterns: `"list_*"`, `"*_info"`.

- Matches are evaluated against the live upstream `tools/list` response on every request.

- Only tools the caller is authorized to see (per the chain’s
  [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)) will match.

### Use Cases

**Frequently-used tools**: Keep high-traffic tools immediately available to reduce search
round-trips.

```yaml
hotTools:
  - "get_weather"
  - "get_user"
```

**Namespace patterns**: Expose all tools from a specific namespace.

```yaml
hotTools:
  - "weather_*"
  - "user_*"
```

## Search Tool Usage

The `search_tools` meta-tool accepts a JSON object with the following parameters:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>query</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>A case-insensitive regular expression to match against tool names and descriptions. Separate alternative keywords with <code>|</code> (spaces match literally).</p></div></div></td></tr><tr><td><div><div><p><code>limit</code></p></div></div></td><td><div><div><p>integer</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum number of results to return per page. If omitted, uses the configured <code>searchResultLimit</code>.</p></div></div></td></tr><tr><td><div><div><p><code>cursor</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Opaque pagination cursor from a prior search’s <code>nextCursor</code> field. Pass it back to fetch the next page.</p></div></div></td></tr></tbody></table>

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "query": "weather",
      "limit": 3
    }
  }
}
```

### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 1 matching tool(s)."
      }
    ],
    "structuredContent": {
      "matches": [
        {
          "name": "get_weather",
          "description": "Return the current weather for a city",
          "inputSchema": {
            "type": "object",
            "required": ["city"],
            "properties": {
              "city": {
                "type": "string"
              }
            }
          }
        }
      ]
    }
  }
}
```

### Pagination

When more tools match than fit on a page, the response includes a `nextCursor` field under
`structuredContent`:

```json
{
  "structuredContent": {
    "matches": [...],
    "nextCursor": "eyJxIjoid2VhdGhlciIsIm8iOjIwfQ=="
  }
}
```

To fetch the next page, pass the cursor back in the `arguments`:

```json
{
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "cursor": "eyJxIjoid2VhdGhlciIsIm8iOjIwfQ=="
    }
  }
}
```

Each page resolves against a fresh upstream `tools/list`, ensuring the correct authorization. The
`query` parameter may be omitted when using a cursor (the cursor carries it).

## Invoke Tool Usage

The `invoke_tool` meta-tool wraps a call to a discovered tool. It accepts:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>name</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The tool name returned from <code>search_tools</code></p></div></div></td></tr><tr><td><div><div><p><code>arguments</code></p></div></div></td><td><div><div><p>object</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The tool’s input parameters as returned in the <code>inputSchema</code> from <code>search_tools</code></p></div></div></td></tr></tbody></table>

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "invoke_tool",
    "arguments": {
      "name": "get_weather",
      "arguments": {
        "city": "San Francisco"
      }
    }
  }
}
```

The policy rewrites this as a native `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "San Francisco"
    }
  }
}
```

All upstream policies see `get_weather` (not `invoke_tool`), ensuring access control, tool mapping,
and other policies operate correctly.

## Filter Chain Ordering

The MCP Tools Progressive Disclosure policy must be positioned after the
[MCP Support Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support) but before any other MCP policies in the filter
chain, particularly before any policy that reads tool names (access control, tool mapping, schema
validation).

If positioned after an access control policy, that policy would see `invoke_tool` (the meta-tool) in
the request and gate the envelope—not the real tool inside—creating an authorization bypass.

## Delegated Authorization

The policy maintains per-caller authorization parity by delegating to the chain:

1.  A `search_tools` call triggers a synthesized `tools/list` request upstream.

2.  The upstream [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control) filters the
    list per caller.

3.  The policy runs the query against the filtered list.

4.  Only tools the caller is authorized to see are included in results.

This ensures:

- Callers don’t see tools they cannot invoke.

- Results reflect live authorization state.

- No caching of authorization decisions.

If no [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control) is present,
`search_tools` returns the full unfiltered catalog—the same as a direct `tools/list` would in that
chain.

## Error Responses

The policy returns JSON-RPC error objects with a stable `data.reason` field for machine-checkable
error handling.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Case</th><th>Code</th><th><code>data.reason</code></th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Malformed <code>invoke_tool</code></p></div></div></td><td><div><div><p><code>-32602</code></p></div></div></td><td><div><div><p><code>invalid_params</code></p></div></div></td><td><div><div><p>Missing or invalid <code>arguments.name</code> or <code>arguments.arguments</code></p></div></div></td></tr><tr><td><div><div><p>Malformed <code>search_tools</code></p></div></div></td><td><div><div><p><code>-32602</code></p></div></div></td><td><div><div><p><code>invalid_params</code></p></div></div></td><td><div><div><p>Empty/missing/non-string query, exceeds 256 characters, invalid regex, bad <code>limit</code>, missing <code>id</code>, malformed <code>cursor</code>, or <code>cursor</code>/<code>query</code> mismatch</p></div></div></td></tr></tbody></table>

Errors produced upstream (access control denials, upstream tool errors) pass through unchanged.

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping)

- [MCP Global Access](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

<!-- document id=238476511d8920c3798484b638c57ddb98bc00dce77641a73e69475b6afbdbfd url=/mulesoft/current/en-us/gateway/1.12/policies-included-message-logging.md -->

# Message Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Flex Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.0.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The Message Logging policy logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint.

## [](#prerequisites)Prerequisites

You must have the Anypoint Platform Organization Administrators role or have permission to create or manage APIs.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of configurations</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.message</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to the message log. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.conditional</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to whether the message should be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.category</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Default category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Log message prefix that indicates the package and class where the log is executed.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.level</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code><br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.firstSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged before the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.secondSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged after the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration:
      - itemName: "Config 1"
        itemData:
          message: "#\[payload\]"
          conditional: "#\[attributes.queryParams\['QueryParam'\]=='someValue'\]"
          level: "ERROR"
          firstSection: true
      - itemName: "Config 2"
        itemData:
          message: "#\['literal string'\]"
          level: "WARN"
          secondSection: true
          firstSection: true

### [](#connected-mode)Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

![A form with text fields and checkboxes to set up new logging configurations](/mulesoft/current/en-us/gateway/1.12/_images/apim-message-logging-policy-ui.png)

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required?</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave expression to use for extracting the message to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Conditional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave Boolean expression used to specify whether a message is to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Category</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A prefix in the log message that indicates the package and class where the log is executed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Level</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of message to log: INFO, WARN, ERROR, or DEBUG.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Before Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages before the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">After Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages after the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

#### [](#example-of-message-logging-policy-configured-from-the-ui)Example of Message Logging Policy Configured from the UI

To better understand how to use the Message Logging policy, consider a fictional retail clothier named Les Vetments. To successfully run its e-commerce portal, Les Vetments must audit the status code of the requests made on its website.

For example, if a customer buys or returns a product, or if the company adds or removes a product from its catalog, the transactions must be logged. The IT manager at Les Vetments applies the Message Logging policy to the company APIs to enable logging and viewing any data or transaction changes without making any modifications to the code.

To log the attributes of the incoming and outgoing HTTP message, Les Vetments applies the Message Logging policy to the API with the following UI configurations:

- **Message**: #\[attributes\]
    
    The attributes in the payload must be logged.
- **Conditional**: Blank
    
    Because Les Vetments requires all attributes, no expression to filter messages is specified.
- **Category**: Blank
    
    No prefix is required in the log sentence.
- **Level**: Info
    
    All types of messages are to be logged. The Info log level also includes Warn, Error, or Debug log messages.
- **Before Calling API**: Checked
    
    All transactions that occur before the API is called are to be logged.
- **After calling API**: Checked
    
    All transactions that occur after the API is called are to be logged.

Following this configuration, whenever customers access the Les Vetments catalogue or add or remove items from their carts, or when an item is added or removed from the Les Vetments catalog, logs are generated:

```text
**********************************************************************
* Policy: message-logging-1351146-proxy                              *
* OS encoding: UTF-8, Mule encoding: UTF-8                           *
*                                                                    *
**********************************************************************
21:56:50.147     11/30/2020     Worker-0     [MuleRuntime].uber.06: [message-logging-771181-proxy].771181-message-logging.CPU_LITE @71625864     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpRequestAttributes
{
   Request path=/proxy/1
   Raw request path=/proxy/1
   Method=GET
   Listener path=/proxy/*
   Local Address=/172.25.159.101:8081
   Query String=
   Relative Path=/proxy/1
   Masked Request Path=/1
   Remote Address=/18.191.37.179:21836
   Request Uri=/proxy/1
   Raw request Uri=/proxy/1
   Scheme=http
   Version=HTTP/1.1
   Headers=[
      host=logging-policy.us-e2.cloudhub.io
      x-real-ip=204.14.236.154
      accept=*/*
      user-agent=curl/7.54.0
      x-forwarded-for=204.14.236.154
      x-forwarded-port=80
      x-forwarded-proto=http
      x-sigsci-agentresponse=200
      x-sigsci-mac=7caf3820a5c07d06ef827f1565678167
   ]
   Query Parameters=[]
   URI Parameters=[]
}
21:56:50.254     11/30/2020     Worker-0     [MuleRuntime].uber.07: [logging-policy].proxy.CPU_LITE @f0ce617     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpResponseAttributes
{
   Status Code=200
   Reason Phrase=OK
   Headers=[
      date=Tue, 01 Dec 2020 00:56:50 GMT
      content-type=application/json; charset=utf-8
      set-cookie=__cfduid=d8afa23a4627ebef39cbc54fea223cb231606784210; expires=Thu, 31-Dec-20 00:56:50 GMT; path=/; domain=.typicode.com; HttpOnly; SameSite=Lax
      x-powered-by=Express
      x-ratelimit-limit=1000
      x-ratelimit-remaining=999
      x-ratelimit-reset=1606784265
      vary=Origin, Accept-Encoding
      access-control-allow-credentials=true
      cache-control=max-age=43200
      pragma=no-cache
      expires=-1
      x-content-type-options=nosniff
      etag=W/"53-hfEnumeNh6YirfjyjaujcOPPT+s"
      via=1.1 vegur
      cf-cache-status=MISS
      accept-ranges=bytes
      cf-request-id=06bd666d0a0000386b7a1fc000000001
      expect-ct=max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
      report-to={"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report?s=qUAIXoQ7qqqvFzjcwGrmK2r2PcSfDZ75jFJd0Gi0BLBUMHAcnC9wJ9I%2FEHJtk%2Bra%2FXWqkA%2F5%2FlzoWoC6YS2Lew%2BqKgjhaphHqx5WrZ0CKHMalhcM9it%2Fks0qzQGwbsRzQg%3D%3D"}],"group":"cf-nel","max_age":604800}
      nel={"report_to":"cf-nel","max_age":604800}
      cf-ray=5fa8d9c1a8c6386b-IAD
   ]
}
12:18:31.770     11/18/2020     Worker-0     agw-policy-set-deployment.01     INFO
Applied policy message-logging-1351146 version 1.0.0 to API testLoggingNew-v1-v1:16481163 (16481163) in application messagelog
```

To log headers, Les Vetments uses the following code snippet in the **Message** field:

`#[attributes.headers]`

To customize the log messages based on the event and the action performed, Les Vetments uses the following code snippet in the **Message** field:

`#['User ' authentication.clientId ' performed action ' attributes.method ' on ' attributes.requestPath ' with Payload: ' ++ payload]`

## [](#dataweave-support)DataWeave Expressions Support

The Message Logging policy supports the [standard DataWeave Expressions supported by Flex Gateway policies](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support) and the following additional [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) DataWeave expressions. Format the following expressions `[vars.<expressions>]`, for example `[vars.orgId]`:

- `orgId`
- `masterOrgId`
- `envId`
- `apiId`
- `apiName`
- `apiInstanceName`
- `apiVersion`
- `receivedTs` (rfc3339)
- `repliedTs` (rfc3339, only available in request context)
- `runtimeVersion` (For example: `v1.7.0`)
- `hostId` (For example: `my-host`)
- `reqId` (Referred to as `traceId` in Flex Gateway logs)
- `requestDisposition` (`PROCESSED` or `VIOLATION`, only available in request context)
- `request.remoteAddress`
- `request.method`
- `request.requestPath`
- `request.headers` (all request headers)
- `violation.clientId` (Only available in response context)
- `violation.clientName` (Only available in response context)
- `violation.policyName` (Only available in response context)
- `violation.violationType` (`VIOLATION` or `ERROR`, only available in response context)

## [](#how-this-policy-works)How This Policy Works

Logging a policy consists of the following sequence:

1. A request is sent to the API.
2. The message is logged if the following conditions are true:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy was not set, or was set and the condition was met.
3. The API response is returned. Message Logging Policy does not interfere with the execution of any policy nor its flow.
4. The message appears in the application log.

## [](#about-the-logging-format)About the Logging Format

A message log uses the following format:

`<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>`

- `policy-name`: displays the name of the policy binding:
- `api-name`: displays the name of the api instance:
- `request uuid`: displays a unique identifier for the request that triggered the message.

## [](#logging-states-during-events)Logging States During Events

Message logging occurs at specific intervals during a request flow:

- Before logging an API flow:
    
    ![State before logging an API flow](/mulesoft/current/en-us/gateway/1.12/_images/apim-message-logging-policy-states-1.png)
- After logging an API flow:
    
    ![State after logging an API flow](/mulesoft/current/en-us/gateway/1.12/_images/apim-message-logging-policy-states-2.png)
- Error handler after API flow:
    
    ![State after the error handler executes](/mulesoft/current/en-us/gateway/1.12/_images/apim-message-logging-policy-states-3.png)

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=47aec4281d7ee9345fbcd4cb05a89372de2dc14e71d78707f8d903f6168a5ebc url=/mulesoft/current/en-us/gateway/1.13/policies-included-message-logging.md -->

# Message Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.0.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/message-logging-release-notes" class="xref page">Message Logging</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The Message Logging policy logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">To use multiple log levels for different configurations, add multiple configurations within a single Message Logging policy.</td></tr></tbody></table>

## [](#prerequisites)Prerequisites

You must have the Anypoint Platform Organization Administrators role or have permission to create or manage APIs.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of configurations</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.message</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to the message log. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.conditional</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to whether the message should be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.category</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Default category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Log message prefix that indicates the package and class where the log is executed.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.level</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code><br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.firstSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged before the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.secondSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged after the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration:
      - itemName: "Config 1"
        itemData:
          message: "#\[payload\]"
          conditional: "#\[attributes.queryParams\['QueryParam'\]=='someValue'\]"
          level: "ERROR"
          firstSection: true
      - itemName: "Config 2"
        itemData:
          message: "#\['literal string'\]"
          level: "WARN"
          secondSection: true
          firstSection: true

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

![A form with text fields and checkboxes to set up new logging configurations](/mulesoft/current/en-us/gateway/1.13/_images/apim-message-logging-policy-ui.png)

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required?</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave expression to use for extracting the message to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Conditional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave Boolean expression used to specify whether a message is to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Category</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A prefix in the log message that indicates the package and class where the log is executed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Level</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of message to log: INFO, WARN, ERROR, or DEBUG.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Before Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages before the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">After Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages after the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

#### [](#example-of-message-logging-policy-configured-from-the-ui)Example of Message Logging Policy Configured from the UI

To better understand how to use the Message Logging policy, consider a fictional retail clothier named Les Vetments. To successfully run its e-commerce portal, Les Vetments must audit the status code of the requests made on its website.

For example, if a customer buys or returns a product, or if the company adds or removes a product from its catalog, the transactions must be logged. The IT manager at Les Vetments applies the Message Logging policy to the company APIs to enable logging and viewing any data or transaction changes without making any modifications to the code.

To log the attributes of the incoming and outgoing HTTP message, Les Vetments applies the Message Logging policy to the API with the following UI configurations:

- **Message**: #\[attributes\]
    
    The attributes in the payload must be logged.
- **Conditional**: Blank
    
    Because Les Vetments requires all attributes, no expression to filter messages is specified.
- **Category**: Blank
    
    No prefix is required in the log sentence.
- **Level**: Info
    
    All types of messages are to be logged. The Info log level also includes Warn, Error, or Debug log messages.
- **Before Calling API**: Checked
    
    All transactions that occur before the API is called are to be logged.
- **After calling API**: Checked
    
    All transactions that occur after the API is called are to be logged.

Following this configuration, whenever customers access the Les Vetments catalogue or add or remove items from their carts, or when an item is added or removed from the Les Vetments catalog, logs are generated:

```text
**********************************************************************
* Policy: message-logging-1351146-proxy                              *
* OS encoding: UTF-8, Mule encoding: UTF-8                           *
*                                                                    *
**********************************************************************
21:56:50.147     11/30/2020     Worker-0     [MuleRuntime].uber.06: [message-logging-771181-proxy].771181-message-logging.CPU_LITE @71625864     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpRequestAttributes
{
   Request path=/proxy/1
   Raw request path=/proxy/1
   Method=GET
   Listener path=/proxy/*
   Local Address=/172.25.159.101:8081
   Query String=
   Relative Path=/proxy/1
   Masked Request Path=/1
   Remote Address=/18.191.37.179:21836
   Request Uri=/proxy/1
   Raw request Uri=/proxy/1
   Scheme=http
   Version=HTTP/1.1
   Headers=[
      host=logging-policy.us-e2.cloudhub.io
      x-real-ip=204.14.236.154
      accept=*/*
      user-agent=curl/7.54.0
      x-forwarded-for=204.14.236.154
      x-forwarded-port=80
      x-forwarded-proto=http
      x-sigsci-agentresponse=200
      x-sigsci-mac=7caf3820a5c07d06ef827f1565678167
   ]
   Query Parameters=[]
   URI Parameters=[]
}
21:56:50.254     11/30/2020     Worker-0     [MuleRuntime].uber.07: [logging-policy].proxy.CPU_LITE @f0ce617     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpResponseAttributes
{
   Status Code=200
   Reason Phrase=OK
   Headers=[
      date=Tue, 01 Dec 2020 00:56:50 GMT
      content-type=application/json; charset=utf-8
      set-cookie=__cfduid=d8afa23a4627ebef39cbc54fea223cb231606784210; expires=Thu, 31-Dec-20 00:56:50 GMT; path=/; domain=.typicode.com; HttpOnly; SameSite=Lax
      x-powered-by=Express
      x-ratelimit-limit=1000
      x-ratelimit-remaining=999
      x-ratelimit-reset=1606784265
      vary=Origin, Accept-Encoding
      access-control-allow-credentials=true
      cache-control=max-age=43200
      pragma=no-cache
      expires=-1
      x-content-type-options=nosniff
      etag=W/"53-hfEnumeNh6YirfjyjaujcOPPT+s"
      via=1.1 vegur
      cf-cache-status=MISS
      accept-ranges=bytes
      cf-request-id=06bd666d0a0000386b7a1fc000000001
      expect-ct=max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
      report-to={"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report?s=qUAIXoQ7qqqvFzjcwGrmK2r2PcSfDZ75jFJd0Gi0BLBUMHAcnC9wJ9I%2FEHJtk%2Bra%2FXWqkA%2F5%2FlzoWoC6YS2Lew%2BqKgjhaphHqx5WrZ0CKHMalhcM9it%2Fks0qzQGwbsRzQg%3D%3D"}],"group":"cf-nel","max_age":604800}
      nel={"report_to":"cf-nel","max_age":604800}
      cf-ray=5fa8d9c1a8c6386b-IAD
   ]
}
12:18:31.770     11/18/2020     Worker-0     agw-policy-set-deployment.01     INFO
Applied policy message-logging-1351146 version 1.0.0 to API testLoggingNew-v1-v1:16481163 (16481163) in application messagelog
```

To log headers, Les Vetments uses the following code snippet in the **Message** field:

`#[attributes.headers]`

To customize the log messages based on the event and the action performed, Les Vetments uses the following code snippet in the **Message** field:

`#['User ' authentication.clientId ' performed action ' attributes.method ' on ' attributes.requestPath ' with Payload: ' ++ payload]`

## [](#dataweave-support)DataWeave Expressions Support

The Message Logging policy supports the [standard DataWeave Expressions supported by Omni Gateway policies](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support) and the following additional [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) DataWeave expressions. Format the following expressions `[vars.<expressions>]`, for example `[vars.orgId]`:

- `orgId`
- `masterOrgId`
- `envId`
- `apiId`
- `apiName`
- `apiInstanceName`
- `apiVersion`
- `receivedTs` (rfc3339)
- `repliedTs` (rfc3339, only available in request context)
- `runtimeVersion` (For example: `v1.7.0`)
- `hostId` (For example: `my-host`)
- `reqId` (Referred to as `traceId` in Omni Gateway logs)
- `requestDisposition` (`PROCESSED` or `VIOLATION`, only available in request context)
- `request.remoteAddress`
- `request.method`
- `request.requestPath`
- `request.headers` (all request headers)
- `violation.clientId` (Only available in response context)
- `violation.clientName` (Only available in response context)
- `violation.policyName` (Only available in response context)
- `violation.violationType` (`VIOLATION` or `ERROR`, only available in response context)

## [](#how-this-policy-works)How This Policy Works

Logging a policy consists of the following sequence:

1. A request is sent to the API.
2. The message is logged if the following conditions are true:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy was not set, or was set and the condition was met.
3. The API response is returned. Message Logging Policy does not interfere with the execution of any policy nor its flow.
4. The message appears in the application log.

## [](#about-the-logging-format)About the Logging Format

A message log uses the following format:

`<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>`

- `policy-name`: displays the name of the policy binding:
- `api-name`: displays the name of the api instance:
- `request uuid`: displays a unique identifier for the request that triggered the message.

## [](#logging-states-during-events)Logging States During Events

Message logging occurs at specific intervals during a request flow:

- Before logging an API flow:
    
    ![State before logging an API flow](/mulesoft/current/en-us/gateway/1.13/_images/apim-message-logging-policy-states-1.png)
- After logging an API flow:
    
    ![State after logging an API flow](/mulesoft/current/en-us/gateway/1.13/_images/apim-message-logging-policy-states-2.png)
- Error handler after API flow:
    
    ![State after the error handler executes](/mulesoft/current/en-us/gateway/1.13/_images/apim-message-logging-policy-states-3.png)

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=d9c135a1c6a1c22a8c0c485c5cfde034346d674e0046927ae5697454ab6af4c5 url=/mulesoft/current/en-us/gateway/1.9/policies-included-message-logging.md -->

# Message Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Flex Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.0.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The Message Logging policy logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint.

## [](#prerequisites)Prerequisites

You must have the Anypoint Platform Organization Administrators role or have permission to create or manage APIs.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the following policy definition and table of parameters:

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of configurations</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.message</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to the message log. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.conditional</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to whether the message should be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.category</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Default category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Log message prefix that indicates the package and class where the log is executed.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.level</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code><br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.firstSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged before the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.secondSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged after the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration:
      - itemName: "Config 1"
        itemData:
          message: "#\[payload\]"
          conditional: "#\[attributes.queryParams\['QueryParam'\]=='someValue'\]"
          level: "ERROR"
          firstSection: true
      - itemName: "Config 2"
        itemData:
          message: "#\['literal string'\]"
          level: "WARN"
          secondSection: true
          firstSection: true

### [](#connected-mode)Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

![A form with text fields and checkboxes to set up new logging configurations](/mulesoft/current/en-us/gateway/1.9/_images/apim-message-logging-policy-ui.png)

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required?</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave expression to use for extracting the message to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Conditional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave Boolean expression used to specify whether a message is to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Category</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A prefix in the log message that indicates the package and class where the log is executed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Level</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of message to log: INFO, WARN, ERROR, or DEBUG.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Before Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages before the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">After Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages after the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

#### [](#example-of-message-logging-policy-configured-from-the-ui)Example of Message Logging Policy Configured from the UI

To better understand how to use the Message Logging policy, consider a fictional retail clothier named Les Vetments. To successfully run its e-commerce portal, Les Vetments must audit the status code of the requests made on its website.

For example, if a customer buys or returns a product, or if the company adds or removes a product from its catalog, the transactions must be logged. The IT manager at Les Vetments applies the Message Logging policy to the company APIs to enable logging and viewing any data or transaction changes without making any modifications to the code.

To log the attributes of the incoming and outgoing HTTP message, Les Vetments applies the Message Logging policy to the API with the following UI configurations:

- **Message**: #\[attributes\]
    
    The attributes in the payload must be logged.
- **Conditional**: Blank
    
    Because Les Vetments requires all attributes, no expression to filter messages is specified.
- **Category**: Blank
    
    No prefix is required in the log sentence.
- **Level**: Info
    
    All types of messages are to be logged. The Info log level also includes Warn, Error, or Debug log messages.
- **Before Calling API**: Checked
    
    All transactions that occur before the API is called are to be logged.
- **After calling API**: Checked
    
    All transactions that occur after the API is called are to be logged.

Following this configuration, whenever customers access the Les Vetments catalogue or add or remove items from their carts, or when an item is added or removed from the Les Vetments catalog, logs are generated:

```text
**********************************************************************
* Policy: message-logging-1351146-proxy                              *
* OS encoding: UTF-8, Mule encoding: UTF-8                           *
*                                                                    *
**********************************************************************
21:56:50.147     11/30/2020     Worker-0     [MuleRuntime].uber.06: [message-logging-771181-proxy].771181-message-logging.CPU_LITE @71625864     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpRequestAttributes
{
   Request path=/proxy/1
   Raw request path=/proxy/1
   Method=GET
   Listener path=/proxy/*
   Local Address=/172.25.159.101:8081
   Query String=
   Relative Path=/proxy/1
   Masked Request Path=/1
   Remote Address=/18.191.37.179:21836
   Request Uri=/proxy/1
   Raw request Uri=/proxy/1
   Scheme=http
   Version=HTTP/1.1
   Headers=[
      host=logging-policy.us-e2.cloudhub.io
      x-real-ip=204.14.236.154
      accept=*/*
      user-agent=curl/7.54.0
      x-forwarded-for=204.14.236.154
      x-forwarded-port=80
      x-forwarded-proto=http
      x-sigsci-agentresponse=200
      x-sigsci-mac=7caf3820a5c07d06ef827f1565678167
   ]
   Query Parameters=[]
   URI Parameters=[]
}
21:56:50.254     11/30/2020     Worker-0     [MuleRuntime].uber.07: [logging-policy].proxy.CPU_LITE @f0ce617     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpResponseAttributes
{
   Status Code=200
   Reason Phrase=OK
   Headers=[
      date=Tue, 01 Dec 2020 00:56:50 GMT
      content-type=application/json; charset=utf-8
      set-cookie=__cfduid=d8afa23a4627ebef39cbc54fea223cb231606784210; expires=Thu, 31-Dec-20 00:56:50 GMT; path=/; domain=.typicode.com; HttpOnly; SameSite=Lax
      x-powered-by=Express
      x-ratelimit-limit=1000
      x-ratelimit-remaining=999
      x-ratelimit-reset=1606784265
      vary=Origin, Accept-Encoding
      access-control-allow-credentials=true
      cache-control=max-age=43200
      pragma=no-cache
      expires=-1
      x-content-type-options=nosniff
      etag=W/"53-hfEnumeNh6YirfjyjaujcOPPT+s"
      via=1.1 vegur
      cf-cache-status=MISS
      accept-ranges=bytes
      cf-request-id=06bd666d0a0000386b7a1fc000000001
      expect-ct=max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
      report-to={"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report?s=qUAIXoQ7qqqvFzjcwGrmK2r2PcSfDZ75jFJd0Gi0BLBUMHAcnC9wJ9I%2FEHJtk%2Bra%2FXWqkA%2F5%2FlzoWoC6YS2Lew%2BqKgjhaphHqx5WrZ0CKHMalhcM9it%2Fks0qzQGwbsRzQg%3D%3D"}],"group":"cf-nel","max_age":604800}
      nel={"report_to":"cf-nel","max_age":604800}
      cf-ray=5fa8d9c1a8c6386b-IAD
   ]
}
12:18:31.770     11/18/2020     Worker-0     agw-policy-set-deployment.01     INFO
Applied policy message-logging-1351146 version 1.0.0 to API testLoggingNew-v1-v1:16481163 (16481163) in application messagelog
```

To log headers, Les Vetments uses the following code snippet in the **Message** field:

`#[attributes.headers]`

To customize the log messages based on the event and the action performed, Les Vetments uses the following code snippet in the **Message** field:

`#['User ' authentication.clientId ' performed action ' attributes.method ' on ' attributes.requestPath ' with Payload: ' ++ payload]`

## [](#dataweave-support)DataWeave Expressions Support

The Message Logging policy supports the [standard DataWeave Expressions supported by Flex Gateway policies](https://docs.mulesoft.com/gateway/1.9/policies-flex-dataweave-support) and the following additional [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) DataWeave expressions. Format the following expressions `[vars.<expressions>]`, for example `[vars.orgId]`:

- `orgId`
- `masterOrgId`
- `envId`
- `apiId`
- `apiName`
- `apiInstanceName`
- `apiVersion`
- `receivedTs` (rfc3339)
- `repliedTs` (rfc3339, only available in request context)
- `runtimeVersion` (For example: `v1.7.0`)
- `hostId` (For example: `my-host`)
- `reqId` (Referred to as `traceId` in Flex Gateway logs)
- `requestDisposition` (`PROCESSED` or `VIOLATION`, only available in request context)
- `request.remoteAddress`
- `request.method`
- `request.requestPath`
- `request.headers` (all request headers)
- `violation.clientId` (Only available in response context)
- `violation.clientName` (Only available in response context)
- `violation.policyName` (Only available in response context)
- `violation.violationType` (`VIOLATION` or `ERROR`, only available in response context)

## [](#how-this-policy-works)How This Policy Works

Logging a policy consists of the following sequence:

1. A request is sent to the API.
2. The message is logged if the following conditions are true:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy was not set, or was set and the condition was met.
3. The API response is returned. Message Logging Policy does not interfere with the execution of any policy nor its flow.
4. The message appears in the application log.

## [](#about-the-logging-format)About the Logging Format

A message log uses the following format:

`<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>`

- `policy-name`: displays the name of the policy binding:
- `api-name`: displays the name of the api instance:
- `request uuid`: displays a unique identifier for the request that triggered the message.

## [](#logging-states-during-events)Logging States During Events

Message logging occurs at specific intervals during a request flow:

- Before logging an API flow:
    
    ![State before logging an API flow](/mulesoft/current/en-us/gateway/1.9/_images/apim-message-logging-policy-states-1.png)
- After logging an API flow:
    
    ![State after logging an API flow](/mulesoft/current/en-us/gateway/1.9/_images/apim-message-logging-policy-states-2.png)
- Error handler after API flow:
    
    ![State after the error handler executes](/mulesoft/current/en-us/gateway/1.9/_images/apim-message-logging-policy-states-3.png)

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=dfff9992de384fee6c0e4e9c05d132bdc05ab221827e9c667fdab547ec1cb7d3 url=/mulesoft/current/en-us/gateway/latest/policies-included-message-logging.md -->

# Message Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.0.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/message-logging-release-notes" class="xref page">Message Logging</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The Message Logging policy logs custom messages using information from incoming requests, responses from the backend, or information from other policies applied to the same API endpoint.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">To use multiple log levels for different configurations, add multiple configurations within a single Message Logging policy.</td></tr></tbody></table>

## [](#prerequisites)Prerequisites

You must have the Anypoint Platform Organization Administrators role or have permission to create or manage APIs.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL
    enableDataMasking: <bool> // OPTIONAL
    dataMasking: // OPTIONAL
      entities:
        - <string> // Supported values: Email, US SSN, Credit Card, Phone Number
      customPatterns:
        - name: <string>
          pattern: <string>

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of configurations</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.message</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to the message log. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.conditional</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to whether the message should be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.category</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Default category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Log message prefix that indicates the package and class where the log is executed.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.level</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code><br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.firstSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged before the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.secondSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged after the API endpoint is called, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>enableDataMasking</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>When enabled, the policy detects and masks configured PII in log messages before they are written. Request and response bodies are forwarded to the upstream service unchanged.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>dataMasking.entities</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>[]</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of built-in PII types to mask. Supported values: <code>Email</code>, <code>US SSN</code>, <code>Credit Card</code>, and <code>Phone Number</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>dataMasking.customPatterns</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>[]</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of custom patterns to mask when built-in PII detection doesn’t cover the value. Each pattern must have a <code>name</code> and a <code>pattern</code> (regular expression) property.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

\- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration:
      - itemName: "Config 1"
        itemData:
          message: "#\[payload\]"
          conditional: "#\[attributes.queryParams\['QueryParam'\]=='someValue'\]"
          level: "ERROR"
          firstSection: true
      - itemName: "Config 2"
        itemData:
          message: "#\['literal string'\]"
          level: "WARN"
          secondSection: true
          firstSection: true

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

![A form with text fields and checkboxes to set up new logging configurations](/mulesoft/current/en-us/gateway/latest/_images/apim-message-logging-policy-ui.png)

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required?</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave expression to use for extracting the message to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Conditional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave Boolean expression used to specify whether a message is to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Category</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A prefix in the log message that indicates the package and class where the log is executed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Level</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of message to log: INFO, WARN, ERROR, or DEBUG.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Before Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages before the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">After Calling API</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages after the API endpoint is called, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enable data masking</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detect and mask configured PII before writing log messages. Request and response bodies are forwarded to the upstream service unchanged.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">PII Detection</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Select built-in PII types to mask: Email, US SSN, Credit Card, and Phone Number.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Custom Patterns</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Add a regular expression pattern to mask a value that built-in PII detection doesn’t cover. Each pattern has a name and a regex.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

#### [](#example-of-message-logging-policy-configured-from-the-ui)Example of Message Logging Policy Configured from the UI

To better understand how to use the Message Logging policy, consider a fictional retail clothier named Les Vetments. To successfully run its e-commerce portal, Les Vetments must audit the status code of the requests made on its website.

For example, if a customer buys or returns a product, or if the company adds or removes a product from its catalog, the transactions must be logged. The IT manager at Les Vetments applies the Message Logging policy to the company APIs to enable logging and viewing any data or transaction changes without making any modifications to the code.

To log the attributes of the incoming and outgoing HTTP message, Les Vetments applies the Message Logging policy to the API with the following UI configurations:

- **Message**: #\[attributes\]
    
    The attributes in the payload must be logged.
- **Conditional**: Blank
    
    Because Les Vetments requires all attributes, no expression to filter messages is specified.
- **Category**: Blank
    
    No prefix is required in the log sentence.
- **Level**: Info
    
    All types of messages are to be logged. The Info log level also includes Warn, Error, or Debug log messages.
- **Before Calling API**: Checked
    
    All transactions that occur before the API is called are to be logged.
- **After calling API**: Checked
    
    All transactions that occur after the API is called are to be logged.

Following this configuration, whenever customers access the Les Vetments catalogue or add or remove items from their carts, or when an item is added or removed from the Les Vetments catalog, logs are generated:

```text
**********************************************************************
* Policy: message-logging-1351146-proxy                              *
* OS encoding: UTF-8, Mule encoding: UTF-8                           *
*                                                                    *
**********************************************************************
21:56:50.147     11/30/2020     Worker-0     [MuleRuntime].uber.06: [message-logging-771181-proxy].771181-message-logging.CPU_LITE @71625864     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpRequestAttributes
{
   Request path=/proxy/1
   Raw request path=/proxy/1
   Method=GET
   Listener path=/proxy/*
   Local Address=/172.25.159.101:8081
   Query String=
   Relative Path=/proxy/1
   Masked Request Path=/1
   Remote Address=/18.191.37.179:21836
   Request Uri=/proxy/1
   Raw request Uri=/proxy/1
   Scheme=http
   Version=HTTP/1.1
   Headers=[
      host=logging-policy.us-e2.cloudhub.io
      x-real-ip=204.14.236.154
      accept=*/*
      user-agent=curl/7.54.0
      x-forwarded-for=204.14.236.154
      x-forwarded-port=80
      x-forwarded-proto=http
      x-sigsci-agentresponse=200
      x-sigsci-mac=7caf3820a5c07d06ef827f1565678167
   ]
   Query Parameters=[]
   URI Parameters=[]
}
21:56:50.254     11/30/2020     Worker-0     [MuleRuntime].uber.07: [logging-policy].proxy.CPU_LITE @f0ce617     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpResponseAttributes
{
   Status Code=200
   Reason Phrase=OK
   Headers=[
      date=Tue, 01 Dec 2020 00:56:50 GMT
      content-type=application/json; charset=utf-8
      set-cookie=__cfduid=d8afa23a4627ebef39cbc54fea223cb231606784210; expires=Thu, 31-Dec-20 00:56:50 GMT; path=/; domain=.typicode.com; HttpOnly; SameSite=Lax
      x-powered-by=Express
      x-ratelimit-limit=1000
      x-ratelimit-remaining=999
      x-ratelimit-reset=1606784265
      vary=Origin, Accept-Encoding
      access-control-allow-credentials=true
      cache-control=max-age=43200
      pragma=no-cache
      expires=-1
      x-content-type-options=nosniff
      etag=W/"53-hfEnumeNh6YirfjyjaujcOPPT+s"
      via=1.1 vegur
      cf-cache-status=MISS
      accept-ranges=bytes
      cf-request-id=06bd666d0a0000386b7a1fc000000001
      expect-ct=max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
      report-to={"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report?s=qUAIXoQ7qqqvFzjcwGrmK2r2PcSfDZ75jFJd0Gi0BLBUMHAcnC9wJ9I%2FEHJtk%2Bra%2FXWqkA%2F5%2FlzoWoC6YS2Lew%2BqKgjhaphHqx5WrZ0CKHMalhcM9it%2Fks0qzQGwbsRzQg%3D%3D"}],"group":"cf-nel","max_age":604800}
      nel={"report_to":"cf-nel","max_age":604800}
      cf-ray=5fa8d9c1a8c6386b-IAD
   ]
}
12:18:31.770     11/18/2020     Worker-0     agw-policy-set-deployment.01     INFO
Applied policy message-logging-1351146 version 1.0.0 to API testLoggingNew-v1-v1:16481163 (16481163) in application messagelog
```

To log headers, Les Vetments uses the following code snippet in the **Message** field:

`#[attributes.headers]`

To customize the log messages based on the event and the action performed, Les Vetments uses the following code snippet in the **Message** field:

`#['User ' authentication.clientId ' performed action ' attributes.method ' on ' attributes.requestPath ' with Payload: ' ++ payload]`

## [](#dataweave-support)DataWeave Expressions Support

The Message Logging policy supports the [standard DataWeave Expressions supported by Omni Gateway policies](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support) and the following additional [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) DataWeave expressions. Format the following expressions `[vars.<expressions>]`, for example `[vars.orgId]`:

- `orgId`
- `masterOrgId`
- `envId`
- `apiId`
- `apiName`
- `apiInstanceName`
- `apiVersion`
- `receivedTs` (rfc3339)
- `repliedTs` (rfc3339, only available in request context)
- `runtimeVersion` (For example: `v1.7.0`)
- `hostId` (For example: `my-host`)
- `reqId` (Referred to as `traceId` in Omni Gateway logs)
- `requestDisposition` (`PROCESSED` or `VIOLATION`, only available in request context)
- `request.remoteAddress`
- `request.method`
- `request.requestPath`
- `request.headers` (all request headers)
- `violation.clientId` (Only available in response context)
- `violation.clientName` (Only available in response context)
- `violation.policyName` (Only available in response context)
- `violation.violationType` (`VIOLATION` or `ERROR`, only available in response context)

## [](#how-this-policy-works)How This Policy Works

Logging a policy consists of the following sequence:

1. A request is sent to the API.
2. The message is logged if the following conditions are true:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy was not set, or was set and the condition was met.
3. The API response is returned. Message Logging Policy does not interfere with the execution of any policy nor its flow.
4. The message appears in the application log.

## [](#about-the-logging-format)About the Logging Format

A message log uses the following format:

`<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>`

- `policy-name`: displays the name of the policy binding:
- `api-name`: displays the name of the api instance:
- `request uuid`: displays a unique identifier for the request that triggered the message.

## [](#logging-states-during-events)Logging States During Events

Message logging occurs at specific intervals during a request flow:

- Before logging an API flow:
    
    ![State before logging an API flow](/mulesoft/current/en-us/gateway/latest/_images/apim-message-logging-policy-states-1.png)
- After logging an API flow:
    
    ![State after logging an API flow](/mulesoft/current/en-us/gateway/latest/_images/apim-message-logging-policy-states-2.png)
- Error handler after API flow:
    
    ![State after the error handler executes](/mulesoft/current/en-us/gateway/latest/_images/apim-message-logging-policy-states-3.png)

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=b0ed1b86c9f21815e1b99ce75e518ea68515ed066602ba4691a3152f18bff2c7 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-model-proxy-redirect.md -->

---
product: Omni Gateway
version: 1.12
---

# Model Proxy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Model Proxy documentation has moved to the Enhanced MuleSoft Experience.

See [Enhanced MuleSoft Experience Overview](https://docs.mulesoft.com/general/exp-overview) to learn more about managing
Model proxies and AI services.

For Model Proxy documentation, see [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy).

<!-- document id=35d428f34e03e4634693cb63b5c130690bfcd5ca2b619474d700cfbe62c967e3 url=/mulesoft/current/en-us/gateway/1.13/model-proxy-redirect.md -->

---
product: Omni Gateway
version: 1.13
---

# Model Proxy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Model proxy documentation has moved to the Enhanced MuleSoft Experience.

See [Enhanced MuleSoft Experience Overview](https://docs.mulesoft.com/general/exp-overview) to learn more about managing
model proxies and AI services.

For Model Proxy documentation, see [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy).

<!-- document id=fd7d7eb728f065d6e08b330ba577b3ad6132060893737e1dc79770ec58b3d175 url=/mulesoft/current/en-us/gateway/latest/model-proxy-redirect.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Model Proxy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Model proxy documentation has moved to the Enhanced MuleSoft Experience.

See [Enhanced MuleSoft Experience Overview](https://docs.mulesoft.com/general/exp-overview) to learn more about managing
model proxies and AI services.

For Model Proxy documentation, see [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy).

<!-- document id=a64ca4a1ee446ff890a8b4b25b276692dd256b2535145341a3e76e448ce85469 url=/mulesoft/current/en-us/gateway/1.13/policies-included-llm-proxy-request-compression.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, llm, model proxy, compression, tokens, toon
---

# Model Proxy Request Compression Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Model Proxy Request Compression Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Compresses message content and replayed tool results in Model Proxy request bodies before they reach the upstream provider, reducing billed tokens</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-proxy-request-compression-release-notes">Model Proxy Request Compression</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Model Proxy Request Compression policy reduces token consumption by compressing the strings that
agents carry in an LLM request body before that body reaches the upstream provider.

In an ongoing agent conversation, each message and each tool result is added to the conversation
history. To keep context, a client or runtime might resend the whole history with each new request.
Every time it does, the provider charges input tokens for that history again. Compressing those
repeated strings reduces the input tokens.

The policy scans the entire request body and rewrites each scope-selected string, keeping the
rewritten value only when it is strictly smaller than the original. It supports both the Chat
Completions and Responses API shapes.

Two independent **compression scopes** control which strings are eligible:

- **Compress Tool Results** - Compresses every supplied tool result, including replayed history.
  This covers Chat Completions tool-message content and outputs from Responses function and
  custom-tool calls. Enabled by default to preserve the policy’s original behavior.

- **Compress Messages** - Compresses the Responses `instructions` field and the textual content of
  every supplied system, user, and assistant message, including history. Roles, tool calls,
  metadata, cache breakpoints, and non-text content are preserved. Disabled by default because
  message content might contain formatting-sensitive instructions or data.

Both scopes traverse the whole request rather than only the latest message. When a runtime resends
the raw history in the request body, the policy rewrites it the same way every time, which keeps
prompt-cache prefixes stable. History that the provider manages server-side is never part of the
request body, so the policy neither transforms nor reconstructs it.

The transforms applied within those scopes are organized into two independent features:

1.  **Clean Payload** - Compresses each eligible string using a configurable set of transforms:
    minify (removes only whitespace, so no data is lost), remove null values, remove empty values,
    and HTML to Markdown. Enabled by default.

2.  **TOON Encoding** - Re-encodes uniform JSON structures as Token-Oriented Object Notation (TOON),
    a compact tabular format that reduces tokens for repeated structures. Disabled by default.

The policy is **fail-open** throughout: any gate miss, parse failure, or result that doesn’t get
smaller forwards the original bytes unchanged. When compression does engage, the policy measures the
tokens and bytes saved and feeds the token/cost savings to Cost Management telemetry.

## Placement

Apply this policy to the inbound Model Proxy chain:

- **After** the Model Proxy core processing.

- **Before** any provider transcoding policy, so it operates on the request before it is rewritten
  for a specific provider.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Model Proxy Request Compression policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

The policy configuration is organized into two compression scopes that select which strings are
eligible, plus two transform features. Each feature has a switch that enables the fields below it
and an **Agent IDs** allowlist that controls which agents the feature applies to.

### Compression Scopes

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Compress Tool Results</p></div></div></td><td><div><div><p>Applies the enabled transforms to every supplied tool result, including replayed history. Covers Chat Completions tool-message content and Responses function and custom-tool call outputs.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Compress Messages</p></div></div></td><td><div><div><p>Applies the enabled transforms to the Responses <code>instructions</code> field and the textual content of every supplied system, user, and assistant message, including history. Roles, tool calls, metadata, cache breakpoints, and non-text content are preserved.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr></tbody></table>

### Clean Payload

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Enable Clean Payload</p></div></div></td><td><div><div><p>Enablement switch for the Clean Payload feature.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Minify</p></div></div></td><td><div><div><p>Reserializes eligible JSON content in compact form, dropping only insignificant whitespace such as indentation and spaces between tokens. The parsed data is unchanged, so no information is lost.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Remove Null Values</p></div></div></td><td><div><div><p>Lossy. Recursively drops object keys with <code>null</code> values from eligible JSON content. Null array elements are preserved.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Remove Empty Values</p></div></div></td><td><div><div><p>Drops object keys whose value is an empty string, array, or object, applied bottom-up until no more can be removed.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>HTML to Markdown</p></div></div></td><td><div><div><p>Converts eligible HTML content to Markdown after stripping <code>&lt;script&gt;</code> and <code>&lt;style&gt;</code> blocks. If the conversion fails, the policy falls back to that stripped HTML instead of erroring.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Clean Payload — Agent IDs</p></div></div></td><td><div><div><p>Allowlist of agent IDs opted into the Clean Payload feature. For details on allowlist behavior, see <a href="#agent-id-gating">Per-Agent Gating</a>.</p></div></div></td><td><div><div><p><code>[]</code> (empty)</p></div></div></td></tr></tbody></table>

### TOON Encoding

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Enable TOON Encoding</p></div></div></td><td><div><div><p>Enablement switch for the TOON feature.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>TOON Minimum Response Bytes</p></div></div></td><td><div><div><p>Apply TOON encoding only to eligible strings that are at least this many bytes long. A value of <code>0</code> disables the threshold.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>TOON — Agent IDs</p></div></div></td><td><div><div><p>Allowlist of agent IDs opted into the TOON feature. For details on allowlist behavior, see <a href="#agent-id-gating">Per-Agent Gating</a>.</p></div></div></td><td><div><div><p><code>[]</code> (empty)</p></div></div></td></tr></tbody></table>

### Per-Agent Gating

Each feature has its own **Agent IDs** independent allowlist (**Clean Payload — Agent IDs** and
**TOON — Agent IDs**). The policy resolves the agent ID from the request and decides to apply the
feature to:

- Direct requests to the Model Proxy that carry no agent ID. The feature always applies to these
  requests, regardless of the allowlist contents.

- Requests from an identified agent specified in the allowlist.

You must add an agent to the allowlist for the the feature to apply to its request. There is no
allow-all functionality.

In Cost Management, applying the policy to an agent appends the agent’s ID to the allowlist of the
enabled feature.

## How This Policy Works

For each request, the policy processes the body only when these conditions are met:

- The request is a `POST` with a `Content-Type` of `application/json`.

- The request has been normalized to OpenAI shape by the upstream Model Proxy core processing.

When those conditions are met, the policy:

1.  Determines which scopes and features are engaged and if the agent is in a per-agent allowlist.

2.  Scans the full request body and locates the scope-selected strings, in document order, across
    the complete supplied history.

3.  Rewrites each located string.

4.  Keeps a rewritten string only when it is strictly smaller than the original.

5.  Removes the stale `Content-Length` header and reserializes the body.

Because the policy is fail-open, an unparseable body, a missing gate, or a result that does not
shrink causes the original request to pass through unchanged, and no savings are reported.

### TOON Encoding

Token-Oriented Object Notation (TOON) is a compact, JSON-equivalent text format that reduces token
consumption for structured data. When **Enable TOON Encoding** is enabled, the policy re-encodes
eligible JSON content as TOON, prefixing the result with \`TOON: \`.

TOON encoding:

- Applies only to eligible strings that are at least **TOON Minimum Response Bytes**.

- Applies only to the shapes that TOON can shrink, such as uniform arrays of objects and objects
  with repeated structure.

- Is lossless but format-changing: the data is preserved, but the model receives it as TOON rather
  than JSON.

- Preserves or reduces payload size: the re-encoded value is kept only when it is strictly smaller
  than the original.

## See Also

- [MCP Payload Optimization Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-payload-optimization)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

<!-- document id=50bff54214496c0c4c7c56a7cfb463372e00a23b5530d45abab07a51eb033105 url=/mulesoft/current/en-us/gateway/latest/policies-included-llm-proxy-request-compression.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, model proxy, compression, tokens, toon
---

# Model Proxy Request Compression Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Model Proxy Request Compression Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Compresses message content and replayed tool results in Model Proxy request bodies before they reach the upstream provider, reducing billed tokens</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-proxy-request-compression-release-notes">Model Proxy Request Compression</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

The Model Proxy Request Compression policy reduces token consumption by compressing the strings that
agents carry in an LLM request body before that body reaches the upstream provider.

In an ongoing agent conversation, each message and each tool result is added to the conversation
history. To keep context, a client or runtime might resend the whole history with each new request.
Every time it does, the provider charges input tokens for that history again. Compressing those
repeated strings reduces the input tokens.

The policy scans the entire request body and rewrites each scope-selected string, keeping the
rewritten value only when it is strictly smaller than the original. It supports both the Chat
Completions and Responses API shapes.

Two independent **compression scopes** control which strings are eligible:

- **Compress Tool Results** - Compresses every supplied tool result, including replayed history.
  This covers Chat Completions tool-message content and outputs from Responses function and
  custom-tool calls. Enabled by default to preserve the policy’s original behavior.

- **Compress Messages** - Compresses the Responses `instructions` field and the textual content of
  every supplied system, user, and assistant message, including history. Roles, tool calls,
  metadata, cache breakpoints, and non-text content are preserved. Disabled by default because
  message content might contain formatting-sensitive instructions or data.

Both scopes traverse the whole request rather than only the latest message. When a runtime resends
the raw history in the request body, the policy rewrites it the same way every time, which keeps
prompt-cache prefixes stable. History that the provider manages server-side is never part of the
request body, so the policy neither transforms nor reconstructs it.

The transforms applied within those scopes are organized into two independent features:

1.  **Clean Payload** - Compresses each eligible string using a configurable set of transforms:
    minify (removes only whitespace, so no data is lost), remove null values, remove empty values,
    and HTML to Markdown. Enabled by default.

2.  **TOON Encoding** - Re-encodes uniform JSON structures as Token-Oriented Object Notation (TOON),
    a compact tabular format that reduces tokens for repeated structures. Disabled by default.

The policy is **fail-open** throughout: any gate miss, parse failure, or result that doesn’t get
smaller forwards the original bytes unchanged. When compression does engage, the policy measures the
tokens and bytes saved and feeds the token/cost savings to Cost Management telemetry.

## Placement

Apply this policy to the inbound Model Proxy chain:

- **After** the Model Proxy core processing.

- **Before** any provider transcoding policy, so it operates on the request before it is rewritten
  for a specific provider.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Model Proxy Request Compression policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

The policy configuration is organized into two compression scopes that select which strings are
eligible, plus two transform features. Each feature has a switch that enables the fields below it
and an **Agent IDs** allowlist that controls which agents the feature applies to.

### Compression Scopes

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Compress Tool Results</p></div></div></td><td><div><div><p>Applies the enabled transforms to every supplied tool result, including replayed history. Covers Chat Completions tool-message content and Responses function and custom-tool call outputs.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Compress Messages</p></div></div></td><td><div><div><p>Applies the enabled transforms to the Responses <code>instructions</code> field and the textual content of every supplied system, user, and assistant message, including history. Roles, tool calls, metadata, cache breakpoints, and non-text content are preserved.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr></tbody></table>

### Clean Payload

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Enable Clean Payload</p></div></div></td><td><div><div><p>Enablement switch for the Clean Payload feature.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Minify</p></div></div></td><td><div><div><p>Reserializes eligible JSON content in compact form, dropping only insignificant whitespace such as indentation and spaces between tokens. The parsed data is unchanged, so no information is lost.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td></tr><tr><td><div><div><p>Remove Null Values</p></div></div></td><td><div><div><p>Lossy. Recursively drops object keys with <code>null</code> values from eligible JSON content. Null array elements are preserved.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Remove Empty Values</p></div></div></td><td><div><div><p>Drops object keys whose value is an empty string, array, or object, applied bottom-up until no more can be removed.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>HTML to Markdown</p></div></div></td><td><div><div><p>Converts eligible HTML content to Markdown after stripping <code>&lt;script&gt;</code> and <code>&lt;style&gt;</code> blocks. If the conversion fails, the policy falls back to that stripped HTML instead of erroring.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>Clean Payload — Agent IDs</p></div></div></td><td><div><div><p>Allowlist of agent IDs opted into the Clean Payload feature. For details on allowlist behavior, see <a href="#agent-id-gating">Per-Agent Gating</a>.</p></div></div></td><td><div><div><p><code>[]</code> (empty)</p></div></div></td></tr></tbody></table>

### TOON Encoding

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Enable TOON Encoding</p></div></div></td><td><div><div><p>Enablement switch for the TOON feature.</p></div></div></td><td><div><div><p>Disabled</p></div></div></td></tr><tr><td><div><div><p>TOON Minimum Response Bytes</p></div></div></td><td><div><div><p>Apply TOON encoding only to eligible strings that are at least this many bytes long. A value of <code>0</code> disables the threshold.</p></div></div></td><td><div><div><p><code>500</code></p></div></div></td></tr><tr><td><div><div><p>TOON — Agent IDs</p></div></div></td><td><div><div><p>Allowlist of agent IDs opted into the TOON feature. For details on allowlist behavior, see <a href="#agent-id-gating">Per-Agent Gating</a>.</p></div></div></td><td><div><div><p><code>[]</code> (empty)</p></div></div></td></tr></tbody></table>

### Per-Agent Gating

Each feature has its own **Agent IDs** independent allowlist (**Clean Payload — Agent IDs** and
**TOON — Agent IDs**). The policy resolves the agent ID from the request and decides to apply the
feature to:

- Direct requests to the Model Proxy that carry no agent ID. The feature always applies to these
  requests, regardless of the allowlist contents.

- Requests from an identified agent specified in the allowlist.

You must add an agent to the allowlist for the the feature to apply to its request. There is no
allow-all functionality.

In Cost Management, applying the policy to an agent appends the agent’s ID to the allowlist of the
enabled feature.

## How This Policy Works

For each request, the policy processes the body only when these conditions are met:

- The request is a `POST` with a `Content-Type` of `application/json`.

- The request has been normalized to OpenAI shape by the upstream Model Proxy core processing.

When those conditions are met, the policy:

1.  Determines which scopes and features are engaged and if the agent is in a per-agent allowlist.

2.  Scans the full request body and locates the scope-selected strings, in document order, across
    the complete supplied history.

3.  Rewrites each located string.

4.  Keeps a rewritten string only when it is strictly smaller than the original.

5.  Removes the stale `Content-Length` header and reserializes the body.

Because the policy is fail-open, an unparseable body, a missing gate, or a result that does not
shrink causes the original request to pass through unchanged, and no savings are reported.

### TOON Encoding

Token-Oriented Object Notation (TOON) is a compact, JSON-equivalent text format that reduces token
consumption for structured data. When **Enable TOON Encoding** is enabled, the policy re-encodes
eligible JSON content as TOON, prefixing the result with \`TOON: \`.

TOON encoding:

- Applies only to eligible strings that are at least **TOON Minimum Response Bytes**.

- Applies only to the shapes that TOON can shrink, such as uniform arrays of objects and objects
  with repeated structure.

- Is lossless but format-changing: the data is preserved, but the model receives it as TOON rather
  than JSON.

- Preserves or reduces payload size: the re-encoded value is kept only when it is strictly smaller
  than the original.

## See Also

- [MCP Payload Optimization Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-payload-optimization)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

<!-- document id=66817c39aea818510b9695fec443172de2b32da793e6cbc0180cae96a639398e url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-monitor.md -->

---
product: Omni Gateway
version: 1.12
---

# Monitoring Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway enables you to monitor the state of your APIs and gateway instances, and to view key
metrics.

Refer to the following for details about Flex Gateway monitoring and logging:

- [Monitoring in Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-monitor)

- [Monitoring in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-monitor)

- [Monitoring in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-monitor)

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

<!-- document id=3860f0ec9f9e0feb585637cfde083e43e7356c5a9c977bc21b1794aa472e3870 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-monitor.md -->

---
product: Omni Gateway
version: 1.9
---

# Monitoring Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway enables you to monitor the state of your APIs and gateway instances, and to view key
metrics.

Refer to the following for details about Flex Gateway monitoring and logging:

- [Monitoring in Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-monitor)

- [Monitoring in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-monitor)

- [Monitoring in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-monitor)

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

<!-- document id=02f09ecf5d65431aeb5ca2eab5bdb035f25a96830af47b83708504b67b54a19e url=/mulesoft/current/en-us/gateway/1.12/flex-managed-view-status.md -->

---
product: Omni Gateway
version: 1.12
---

# Monitoring Flex Gateway Metrics

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## View a Managed Flex Gateway Metrics in Runtime Manager

The Managed Flex Gateway Dashboard in Runtime Manager presents a comprehensive view of the gateway,
detailing its status, endpoints, private space, API capacity, request volume, data consumption, and
average CPU and memory usage. In addition, it provides metrics on latency and error count for
thorough monitoring.

To view information about a Managed Flex Gateway Instance:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the name of the Managed Flex Gateway to view its status.

## View Managed Flex Gateway Audit Logs

Access Management audit logs provide a queryable history of actions performed within Anypoint
Platform. Use audit logs to track Managed Flex Gateway actions, such as creating, editing, starting,
and stopping gateways.

To learn more about Audit Logs, see
[Audit Logging in Anypoint Platform](https://docs.mulesoft.com/access-management/audit-logging).

To view Managed Flex Gateway audit logs:

1.  From Anypoint Platform, select **Access Management**.

2.  Click **Audit Logs**.

3.  Click the **Products** drop down.

4.  Select **Managed Gateway**.

<!-- document id=6551417611b117d9165a980cdb46a944c2d38d3cdbc9d3465c848191558cffab url=/mulesoft/current/en-us/gateway/1.12/flex-conn-monitor.md -->

---
product: Omni Gateway
version: 1.12
---

# Monitoring in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway running in Connected Mode enables you to monitor APIs via Anypoint Platform. By using
Anypoint Platform, you can configure logs and view key metrics and analytics.

Refer to the following tasks for details about monitoring in Connected Mode:

- [Configure Message Logging](https://docs.mulesoft.com/gateway/1.12/flex-conn-message-log) - Apply a Message Logging policy to your API
  instance via API Manager. This policy enables you to view basic logs for Flex Gateway APIs.

- [Configure API Alerts](https://docs.mulesoft.com/gateway/1.12/flex-use-api-alerts) - Configure API alerts to receive email notifications
  that flag unusual API behavior.

- [Configure Flex Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.12/flex-conn-third-party-logs-config) -
  Configure log output for consumption by third-party services such as Splunk.

- [View Key Metrics for Flex Gateway APIs](https://docs.mulesoft.com/gateway/1.12/flex-conn-view-api-metrics) - Collect metrics for active
  Flex Gateway APIs via API Manager. You can view charts and filter metrics by date.

- [View the Replica Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.12/flex-view-replica-status) - View Flex Replica
  connection status from Runtime Manager.

- [View the Flex Gateway API Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.12/flex-conn-view-api-status) - View the Flex
  Gateway API status from Runtime Manager.

- [View Runtime Logs in Runtime Manager](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-runtime-manager) - View details of your
  Flex Gateway logs from Runtime Manager.

- [View Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-monitoring) - View details of your Flex
  Gateway logs from within the Anypoint Monitoring UI.

- [Disable Flex Gateway Log Output](https://docs.mulesoft.com/gateway/1.12/flex-conn-disable-logs) - Disable log output to Anypoint
  Platform by using a local declarative configuration file.

<!-- document id=0f57e0a64d7a5dfed8f86e25a2f57134c747dcabf22268d666b65aabb6e369fd url=/mulesoft/current/en-us/gateway/1.13/conn-monitor.md -->

---
product: Omni Gateway
version: 1.13
---

# Monitoring in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Connected Mode enables you to monitor APIs via Anypoint Platform. By using
Anypoint Platform, you can configure logs and view key metrics and analytics.

Refer to the following tasks for details about monitoring in Connected Mode:

- [Configure Message Logging](https://docs.mulesoft.com/gateway/1.13/conn-message-log) - Apply a Message Logging policy to your API
  instance via API Manager. This policy enables you to view basic logs for Omni Gateway APIs.

- [Configure API Alerts](https://docs.mulesoft.com/gateway/1.13/use-api-alerts) - Configure API alerts to receive email notifications that
  flag unusual API behavior.

- [Configure Omni Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.13/conn-third-party-logs-config) -
  Configure log output for consumption by third-party services such as Splunk.

- [View Key Metrics for Omni Gateway APIs](https://docs.mulesoft.com/gateway/1.13/conn-view-api-metrics) - Collect metrics for active Omni
  Gateway APIs via API Manager. You can view charts and filter metrics by date.

- [View the Replica Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.13/view-replica-status) - View Omni Replica connection
  status from Runtime Manager.

- [View the Omni Gateway API Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.13/conn-view-api-status) - View the Omni
  Gateway API status from Runtime Manager.

- [View Runtime Logs in Runtime Manager](https://docs.mulesoft.com/gateway/1.13/view-logs-in-runtime-manager) - View details of your Omni
  Gateway logs from Runtime Manager.

- [View Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.13/view-logs-in-monitoring) - View details of your Omni Gateway
  logs from within the Anypoint Monitoring UI.

- [Disable Omni Gateway Log Output](https://docs.mulesoft.com/gateway/1.13/conn-disable-logs) - Disable log output to Anypoint Platform by
  using a local declarative configuration file.

<!-- document id=737b503de6f635a10880672c49a5ce1f0f448211fe50be7b340a6c2924907a9b url=/mulesoft/current/en-us/gateway/1.9/flex-conn-monitor.md -->

---
product: Omni Gateway
version: 1.9
---

# Monitoring in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway running in Connected Mode enables you to monitor APIs via Anypoint Platform. By using
Anypoint Platform, you can configure logs and view key metrics and analytics.

Refer to the following tasks for details about monitoring in Connected Mode:

- [Configure Message Logging](https://docs.mulesoft.com/gateway/1.9/flex-conn-message-log) - Apply a Message Logging policy to your API
  instance via API Manager. This policy enables you to view basic logs for Flex Gateway APIs.

- [Configure API Alerts](https://docs.mulesoft.com/gateway/1.9/flex-use-api-alerts) - Configure API alerts to receive email notifications
  that flag unusual API behavior.

- [Configure Flex Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.9/flex-conn-third-party-logs-config) -
  Configure log output for consumption by third-party services such as Splunk.

- [View Key Metrics for Flex Gateway APIs](https://docs.mulesoft.com/gateway/1.9/flex-conn-view-api-metrics) - Collect metrics for active
  Flex Gateway APIs via API Manager. You can view charts and filter metrics by date.

- [View the Replica Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.9/flex-view-replica-status) - View Flex Replica
  connection status from Runtime Manager.

- [View the Flex Gateway API Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.9/flex-conn-view-api-status) - View the Flex
  Gateway API status from Runtime Manager.

- [View Runtime Logs in Runtime Manager](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-runtime-manager) - View details of your
  Flex Gateway logs from Runtime Manager.

- [View Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-monitoring) - View details of your Flex
  Gateway logs from within the Anypoint Monitoring UI.

- [Disable Flex Gateway Log Output](https://docs.mulesoft.com/gateway/1.9/flex-conn-disable-logs) - Disable log output to Anypoint
  Platform by using a local declarative configuration file.

<!-- document id=dc0a53a49b467dfcae0fce7aae089fa717a41f9d534118e68a1c0cb19067b283 url=/mulesoft/current/en-us/gateway/latest/conn-monitor.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Monitoring in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Connected Mode enables you to monitor APIs via Anypoint Platform. By using
Anypoint Platform, you can configure logs and view key metrics and analytics.

Refer to the following tasks for details about monitoring in Connected Mode:

- [Configure Message Logging](https://docs.mulesoft.com/gateway/latest/conn-message-log) - Apply a Message Logging policy to your API
  instance via API Manager. This policy enables you to view basic logs for Omni Gateway APIs.

- [Configure API Alerts](https://docs.mulesoft.com/gateway/latest/use-api-alerts) - Configure API alerts to receive email notifications that
  flag unusual API behavior.

- [Configure Omni Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/latest/conn-third-party-logs-config) -
  Configure log output for consumption by third-party services such as Splunk.

- [View Key Metrics for Omni Gateway APIs](https://docs.mulesoft.com/gateway/latest/conn-view-api-metrics) - Collect metrics for active Omni
  Gateway APIs via API Manager. You can view charts and filter metrics by date.

- [View the Replica Status in Runtime Manager](https://docs.mulesoft.com/gateway/latest/view-replica-status) - View Omni Replica connection
  status from Runtime Manager.

- [View the Omni Gateway API Status in Runtime Manager](https://docs.mulesoft.com/gateway/latest/conn-view-api-status) - View the Omni
  Gateway API status from Runtime Manager.

- [View Runtime Logs in Runtime Manager](https://docs.mulesoft.com/gateway/latest/view-logs-in-runtime-manager) - View details of your Omni
  Gateway logs from Runtime Manager.

- [View Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/latest/view-logs-in-monitoring) - View details of your Omni Gateway
  logs from within the Anypoint Monitoring UI.

- [Disable Omni Gateway Log Output](https://docs.mulesoft.com/gateway/latest/conn-disable-logs) - Disable log output to Anypoint Platform by
  using a local declarative configuration file.

<!-- document id=839793afc0af112f8da5a1f62abac59394717ff981448014f77c3c02eae223bc url=/mulesoft/current/en-us/gateway/1.12/flex-local-monitor.md -->

---
product: Omni Gateway
version: 1.12
---

# Monitoring in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway running in Local Mode enables you to monitor APIs independent of Anypoint Platform.
Using declarative configuration files, you configure Flex Gateway to deliver logs to different
Fluent Bit outputs.

Refer to the following tasks for details about monitoring in Local Mode:

- [Configure External Logs for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-third-party-logs-config) -
  Configure log output for Fluent Bit output types. Output types include `File`, `HTTP`, and
  `Splunk`.

- [View Standard Output Logs](https://docs.mulesoft.com/gateway/1.12/flex-local-view-logs) - View Flex Gateway standard output logs.
  Quickly verify the status of external services and API requests.

<!-- document id=1c9ee1a75a1cea86c6dcc8c880edf35714906c5dd4e7a02542c22d73b775e623 url=/mulesoft/current/en-us/gateway/1.13/local-monitor.md -->

---
product: Omni Gateway
version: 1.13
---

# Monitoring in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Local Mode enables you to monitor APIs independent of Anypoint Platform.
Using declarative configuration files, you configure Omni Gateway to deliver logs to different
Fluent Bit outputs.

Refer to the following tasks for details about monitoring in Local Mode:

- [Configure External Logs for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-third-party-logs-config) -
  Configure log output for Fluent Bit output types. Output types include `File`, `HTTP`, and
  `Splunk`.

- [View Standard Output Logs](https://docs.mulesoft.com/gateway/1.13/local-view-logs) - View Omni Gateway standard output logs. Quickly
  verify the status of external services and API requests.

<!-- document id=9c6fc907315e029abd283553dc732c1797747c53275c07a36f00539897ff4819 url=/mulesoft/current/en-us/gateway/1.9/flex-local-monitor.md -->

---
product: Omni Gateway
version: 1.9
---

# Monitoring in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway running in Local Mode enables you to monitor APIs independent of Anypoint Platform.
Using declarative configuration files, you configure Flex Gateway to deliver logs to different
Fluent Bit outputs.

Refer to the following tasks for details about monitoring in Local Mode:

- [Configure External Logs for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-third-party-logs-config) -
  Configure log output for Fluent Bit output types. Output types include `File`, `HTTP`, and
  `Splunk`.

- [View Standard Output Logs](https://docs.mulesoft.com/gateway/1.9/flex-local-view-logs) - View Flex Gateway standard output logs.
  Quickly verify the status of external services and API requests.

<!-- document id=3c4bf9e0d550cda0bcf0284ab9c0bed6195f07d58d386be1a3df47964d57674b url=/mulesoft/current/en-us/gateway/latest/local-monitor.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Monitoring in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Local Mode enables you to monitor APIs independent of Anypoint Platform.
Using declarative configuration files, you configure Omni Gateway to deliver logs to different
Fluent Bit outputs.

Refer to the following tasks for details about monitoring in Local Mode:

- [Configure External Logs for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-third-party-logs-config) -
  Configure log output for Fluent Bit output types. Output types include `File`, `HTTP`, and
  `Splunk`.

- [View Standard Output Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs) - View Omni Gateway standard output logs. Quickly
  verify the status of external services and API requests.

<!-- document id=6dbd342f1aa35491e9b703ecfbeed5c7e3374a8b75c491017dd353afc5cf7a4c url=/mulesoft/current/en-us/gateway/1.12/flex-managed-monitor.md -->

---
product: Omni Gateway
version: 1.12
---

# Monitoring in Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Managed Flex Gateway allows you to access logs and view key metrics.

Refer to these topics for details about monitoring Managed Flex Gateway:

- [Monitoring Flex Gateway Metrics](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-status)

- [Configuring Message Logging for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-message-log)

- [Viewing Key Metrics in API Manager for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-api-metrics)

- [Viewing API Status in Runtime Manager for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-api-status)

- [Viewing Runtime Logs in Runtime Manager for Flex Managed Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-logs-in-runtime-manager)

- [Viewing Managed Flex Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-logs-in-monitoring)

<!-- document id=1df6d903a1ea0275fc24fc41f8740d823039d68bbbcc964834830f18e853ceeb url=/mulesoft/current/en-us/gateway/1.9/flex-managed-monitor.md -->

---
product: Omni Gateway
version: 1.9
---

# Monitoring in Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Managed Flex Gateway allows you to access logs and view key metrics.

Refer to these topics for details about monitoring Managed Flex Gateway:

- [Viewing Managed Flex Gateway Metrics](https://docs.mulesoft.com/gateway/1.9/flex-managed-view-status)

- [Configuring Message Logging for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-message-log)

- [Viewing Key Metrics in API Manager for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-view-api-metrics)

- [Viewing API Status in Runtime Manager for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-view-api-status)

- [Viewing Runtime Logs in Runtime Manager for Flex Managed Gateway](https://docs.mulesoft.com/gateway/1.9/flex-managed-view-logs-in-runtime-manager)

- [Viewing Managed Flex Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.9/flex-managed-view-logs-in-monitoring)

<!-- document id=27748adaed90c4f573c559b5ec2a56bc7a836063a8f4f7796ad78746e451bde4 url=/mulesoft/current/en-us/gateway/1.13/managed-monitor.md -->

---
product: Omni Gateway
version: 1.13
---

# Monitoring in Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Managed Omni Gateway allows you to access logs and view key metrics.

Refer to these topics for details about monitoring Managed Omni Gateway:

- [Monitoring Omni Gateway Metrics](https://docs.mulesoft.com/gateway/1.13/managed-view-status)

- [Configuring Message Logging for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-message-log)

- [Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-view-api-metrics)

- [Viewing API Status in Runtime Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-view-api-status)

- [Viewing Runtime Logs in Runtime Manager for Omni Managed Gateway](https://docs.mulesoft.com/gateway/1.13/managed-view-logs-in-runtime-manager)

- [Viewing Managed Omni Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.13/managed-view-logs-in-monitoring)

<!-- document id=959271331ee41b74d82dcf0bb5d1c2a934b8d2187f50fc3f0bb58e300b2ffd20 url=/mulesoft/current/en-us/gateway/latest/managed-monitor.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Monitoring in Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Managed Omni Gateway allows you to access logs and view key metrics.

Refer to these topics for details about monitoring Managed Omni Gateway:

- [Monitoring Omni Gateway Metrics](https://docs.mulesoft.com/gateway/latest/managed-view-status)

- [Configuring Message Logging for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-message-log)

- [Viewing Key Metrics in API Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-view-api-metrics)

- [Viewing API Status in Runtime Manager for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-view-api-status)

- [Viewing Runtime Logs in Runtime Manager for Omni Managed Gateway](https://docs.mulesoft.com/gateway/latest/managed-view-logs-in-runtime-manager)

- [Viewing Managed Omni Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/latest/managed-view-logs-in-monitoring)

<!-- document id=73e7cf119da0b6f0fc61ae143ec417722d5915e22480321d68d5a5a02ff24547 url=/mulesoft/current/en-us/gateway/1.13/gateway-monitor.md -->

---
product: Omni Gateway
version: 1.13
---

# Monitoring Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables you to monitor the state of your APIs and gateway instances, and to view key
metrics.

Refer to the following for details about Omni Gateway monitoring and logging:

- [Monitoring in Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-monitor)

- [Monitoring in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-monitor)

- [Monitoring in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-monitor)

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

<!-- document id=03b6ac40d57230aaf4529468f3ffb7413a2076f846d320dc581ee4dda932e788 url=/mulesoft/current/en-us/gateway/latest/gateway-monitor.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Monitoring Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway enables you to monitor the state of your APIs and gateway instances, and to view key
metrics.

Refer to the following for details about Omni Gateway monitoring and logging:

- [Monitoring in Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-monitor)

- [Monitoring in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-monitor)

- [Monitoring in Local Mode](https://docs.mulesoft.com/gateway/latest/local-monitor)

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

<!-- document id=0646ef518db01ce11e333f3d890b919d12d2a33112d05231d42f43b214f2dd39 url=/mulesoft/current/en-us/gateway/1.13/managed-view-status.md -->

---
product: Omni Gateway
version: 1.13
---

# Monitoring Omni Gateway Metrics

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## View a Managed Omni Gateway Metrics in Runtime Manager

The Managed Omni Gateway Dashboard in Runtime Manager presents a comprehensive view of the gateway,
detailing its status, endpoints, private space, API capacity, request volume, data consumption, and
average CPU and memory usage. In addition, it provides metrics on latency and error count for
thorough monitoring.

To view information about a Managed Omni Gateway Instance:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the name of the Managed Omni Gateway to view its status.

## View Managed Omni Gateway Audit Logs

Access Management audit logs provide a queryable history of actions performed within Anypoint
Platform. Use audit logs to track Managed Omni Gateway actions, such as creating, editing, starting,
and stopping gateways.

To learn more about Audit Logs, see
[Audit Logging in Anypoint Platform](https://docs.mulesoft.com/access-management/audit-logging).

To view Managed Omni Gateway audit logs:

1.  From Anypoint Platform, select **Access Management**.

2.  Click **Audit Logs**.

3.  Click the **Products** drop down.

4.  Select **Managed Gateway**.

<!-- document id=f8400a4c8aaf5ced8163acf3846795be7e1930b82eaa14b4fc9f6ddc66b77f86 url=/mulesoft/current/en-us/gateway/latest/managed-view-status.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Monitoring Omni Gateway Metrics

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## View a Managed Omni Gateway Metrics in Runtime Manager

The Managed Omni Gateway Dashboard in Runtime Manager presents a comprehensive view of the gateway,
detailing its status, endpoints, private space, API capacity, request volume, data consumption, and
average CPU and memory usage. In addition, it provides metrics on latency and error count for
thorough monitoring.

To view information about a Managed Omni Gateway Instance:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the name of the Managed Omni Gateway to view its status.

## View Managed Omni Gateway Audit Logs

Access Management audit logs provide a queryable history of actions performed within Anypoint
Platform. Use audit logs to track Managed Omni Gateway actions, such as creating, editing, starting,
and stopping gateways.

To learn more about Audit Logs, see
[Audit Logging in Anypoint Platform](https://docs.mulesoft.com/access-management/audit-logging).

To view Managed Omni Gateway audit logs:

1.  From Anypoint Platform, select **Access Management**.

2.  Click **Audit Logs**.

3.  Click the **Products** drop down.

4.  Select **Managed Gateway**.

<!-- document id=504fc37b93b5906c9054f20e8ae425073442dcdc3d762abe91bccb4d403c07fb url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-oauth-obo.md -->

---
product: Omni Gateway
version: 1.12
keywords: oauth2, token exchange, on-behalf-of, obo, rfc 8693, api gateway, flex gateway, gateway, policy
---

# OAuth 2.0 OBO Credential Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 OBO Credential Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Exchanges incoming bearer tokens using OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of, or OAuth 2.0 Token Exchange with CIBA</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The OAuth 2.0 On-Behalf-Of (OBO) Credential Injection policy exchanges an incoming bearer token for
a new token to target specific upstream services. The policy supports OAuth 2.0 Token Exchange (RFC
8693), Microsoft Entra ID On-Behalf-Of protocols, and OAuth 2.0 Token Exchange with Client Initiated
Backchannel Authentication (CIBA). This policy is applied to outbound traffic (gateway to the
backend service) to automatically exchange the OAuth 2.0 token needed for backend services.

The policy extracts the Bearer token from the incoming request’s `Authorization` header and sends a
token exchange request to the token endpoint. The policy then replaces the `Authorization` header
with the new token returned from the token exchange service and forwards the modified request to the
backend service.

To avoid triggering multiple requests for identical tokens, successful token exchanges are cached.
By default, the cache only shares tokens between requests to the same replica. Enable distributed
caching to share tokens between Flex Replicas. To learn more, see
[Token Caching](#token-caching-oauth-obo).

## Configuring Policy Parameters

### Flex Gateway Local Mode

The OAuth 2.0 OBO Credential Injection policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Token Exchange Flow</p></div></div></td><td><div><div><p>Token exchange flow: <strong>OAuth 2.0 Token Exchange</strong> (RFC 8693) or <strong>Microsoft Entra ID On-Behalf-Of</strong>.</p></div></div></td></tr><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p>OAuth 2.0 client ID for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Client Secret</p></div></div></td><td><div><div><p>OAuth 2.0 client secret for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>OAuth 2.0 token endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Target Type</p></div></div></td><td><div><div><p>Parameter type for specifying the target service. Required for OAuth 2.0 Token Exchange flow. Supported values:</p></div><div><ul><li><p>Audience: Logical identifier of the target service (default)</p></li><li><p>Resource: Physical URI of the target resource (RFC 8707)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Target Value</p></div></div></td><td><div><div><p>Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange flow.</p></div></div></td></tr><tr><td><div><div><p>Requested Token Type</p></div></div></td><td><div><div><p>The desired token type URI for the issued token. When omitted, the parameter is not sent and the authorization server selects the issued token type. OAuth 2.0 Token Exchange flow only.</p></div></div></td></tr><tr><td><div><div><p>Subject Token Type</p></div></div></td><td><div><div><p>The token type URI for the incoming subject token from the request <code>Authorization</code> header. By default <code>urn:ietf:params:oauth:token-type:access_token</code>. For JWT tokens, use <code>urn:ietf:params:oauth:token-type:jwt</code>. OAuth 2.0 Token Exchange flow only.</p></div></div></td></tr><tr><td><div><div><p>Scope</p></div></div></td><td><div><div><p>OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, <code>api://downstream-client-id/.default</code>) and OAuth2 Token Exchange with CIBA (for example, <code>openid</code>). Optional for OAuth 2.0 Token Exchange (RFC 8693).</p></div></div></td></tr><tr><td><div><div><p>Timeout</p></div></div></td><td><div><div><p>Timeout for token exchange requests in milliseconds. Default: 10000.</p></div></div></td></tr><tr><td><div><div><p>Enable CIBA</p></div></div></td><td><div><div><p>Enables OAuth 2.0 Token Exchange with CIBA flow. Available only for OAuth 2.0 Token Exchange.</p></div></div></td></tr><tr><td><div><div><p>CIBA Backchannel Endpoint</p></div></div></td><td><div><div><p>The backchannel authentication endpoint (<code>bc-authorize</code>) used to initiate the CIBA flow. Required when <strong>Enable CIBA</strong> is selected.</p></div></div></td></tr><tr><td><div><div><p>Login Hint Claim</p></div></div></td><td><div><div><p>JWT claim from the incoming subject token to send as <code>login_hint</code> in the CIBA request. If no hint is specified, <code>email</code> is used.</p></div></div></td></tr><tr><td><div><div><p>Binding Message</p></div></div></td><td><div><div><p>Optional human-readable message sent as <code>binding_message</code> in the CIBA request and displayed on the authentication device.</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache and CIBA request state are shared across Flex Gateway replicas. Enable this option when running more than one replica to avoid duplicate token exchanges or duplicate CIBA initiations.</p></div></div></td></tr></tbody></table>

## Token Caching

The policy stores each exchanged downstream access token and reuses it when later requests present
the same token. Cached entries are tied to a stable key and expire in line with the token’s
lifetime:

- **TTL**: Cache entry lifetime is derived from the exchanged token.

- If the policy cannot determine expiry, it skips caching for that response. If the policy cannot
  build a cache key, it performs the exchange without using the cache.

- When **Enable CIBA** is enabled, CIBA initiation and polling state, including the approved access
  token, is cached through the same mechanism.

## CIBA Behavior

When **Enable CIBA** is selected, the policy initiates a CIBA backchannel authentication request on
the first matching outbound call and returns an authorization pending response until user
authentication is approved by the authorization server. After approval, the policy injects the
exchanged access token into the `Authorization` header and forwards requests to the backend service.

While waiting for user authentication, the policy returns a `401 Unauthorized` response with the
following JSON body:

HTTP/1.1 401 Unauthorized Retry-After: 5 Content-Type: application/json

{   "error": "authorization\_pending",   "error\_description": "CIBA authorization flow initiated.
Downstream user authorization is in progress. Retry after the indicated interval." }

<!-- document id=eed15548506fd677bf2f8c0bef99a23fe4a25635e0d751c13432c79f34a4c455 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-oauth-obo.md -->

---
product: Omni Gateway
version: 1.13
keywords: oauth2, token exchange, on-behalf-of, obo, rfc 8693, api gateway, flex gateway, gateway, policy
---

# OAuth 2.0 OBO Credential Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 OBO Credential Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Exchanges incoming bearer tokens using OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of, or OAuth 2.0 Token Exchange with CIBA</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-obo-release-notes">OAuth 2.0 OBO Credential Injection</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The OAuth 2.0 On-Behalf-Of (OBO) Credential Injection policy exchanges an incoming bearer token for
a new token to target specific upstream services. The policy supports OAuth 2.0 Token Exchange (RFC
8693), Microsoft Entra ID On-Behalf-Of protocols, and OAuth 2.0 Token Exchange with Client Initiated
Backchannel Authentication (CIBA). This policy is applied to outbound traffic (gateway to the
backend service) to automatically exchange the OAuth 2.0 token needed for backend services.

The policy extracts the Bearer token from the incoming request’s `Authorization` header and sends a
token exchange request to the token endpoint. The policy then replaces the `Authorization` header
with the new token returned from the token exchange service and forwards the modified request to the
backend service.

To avoid triggering multiple requests for identical tokens, successful token exchanges are cached.
By default, the cache only shares tokens between requests to the same replica. Enable distributed
caching to share tokens between Omni Replicas. To learn more, see
[Token Caching](#token-caching-oauth-obo).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The OAuth 2.0 OBO Credential Injection policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Token Exchange Flow</p></div></div></td><td><div><div><p>Token exchange flow: <strong>OAuth 2.0 Token Exchange</strong> (RFC 8693) or <strong>Microsoft Entra ID On-Behalf-Of</strong>.</p></div></div></td></tr><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p>OAuth 2.0 client ID for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Client Secret</p></div></div></td><td><div><div><p>OAuth 2.0 client secret for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>OAuth 2.0 token endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Target Type</p></div></div></td><td><div><div><p>Parameter type for specifying the target service. Required for OAuth 2.0 Token Exchange flow. Supported values:</p></div><div><ul><li><p>Audience: Logical identifier of the target service (default)</p></li><li><p>Resource: Physical URI of the target resource (RFC 8707)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Target Value</p></div></div></td><td><div><div><p>Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange flow.</p></div></div></td></tr><tr><td><div><div><p>Requested Token Type</p></div></div></td><td><div><div><p>The desired token type URI for the issued token. When omitted, the parameter is not sent and the authorization server selects the issued token type. OAuth 2.0 Token Exchange flow only.</p></div></div></td></tr><tr><td><div><div><p>Subject Token Type</p></div></div></td><td><div><div><p>The token type URI for the incoming subject token from the request <code>Authorization</code> header. By default <code>urn:ietf:params:oauth:token-type:access_token</code>. For JWT tokens, use <code>urn:ietf:params:oauth:token-type:jwt</code>. OAuth 2.0 Token Exchange flow only.</p></div></div></td></tr><tr><td><div><div><p>Scope</p></div></div></td><td><div><div><p>OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, <code>api://downstream-client-id/.default</code>) and OAuth2 Token Exchange with CIBA (for example, <code>openid</code>). Optional for OAuth 2.0 Token Exchange (RFC 8693).</p></div></div></td></tr><tr><td><div><div><p>Timeout</p></div></div></td><td><div><div><p>Timeout for token exchange requests in milliseconds. Default: 10000.</p></div></div></td></tr><tr><td><div><div><p>Enable CIBA</p></div></div></td><td><div><div><p>Enables OAuth 2.0 Token Exchange with CIBA flow. Available only for OAuth 2.0 Token Exchange.</p></div></div></td></tr><tr><td><div><div><p>CIBA Backchannel Endpoint</p></div></div></td><td><div><div><p>The backchannel authentication endpoint (<code>bc-authorize</code>) used to initiate the CIBA flow. Required when <strong>Enable CIBA</strong> is selected.</p></div></div></td></tr><tr><td><div><div><p>Login Hint Claim</p></div></div></td><td><div><div><p>JWT claim from the incoming subject token to send as <code>login_hint</code> in the CIBA request. If no hint is specified, <code>email</code> is used.</p></div></div></td></tr><tr><td><div><div><p>Binding Message</p></div></div></td><td><div><div><p>Optional human-readable message sent as <code>binding_message</code> in the CIBA request and displayed on the authentication device.</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache and CIBA request state are shared across Omni Gateway replicas. Enable this option when running more than one replica to avoid duplicate token exchanges or duplicate CIBA initiations.</p></div></div></td></tr></tbody></table>

## Token Caching

The policy stores each exchanged downstream access token and reuses it when later requests present
the same token. Cached entries are tied to a stable key and expire in line with the token’s
lifetime:

- **TTL**: Cache entry lifetime is derived from the exchanged token.

- If the policy cannot determine expiry, it skips caching for that response. If the policy cannot
  build a cache key, it performs the exchange without using the cache.

- When **Enable CIBA** is enabled, CIBA initiation and polling state, including the approved access
  token, is cached through the same mechanism.

## CIBA Behavior

When **Enable CIBA** is selected, the policy initiates a CIBA backchannel authentication request on
the first matching outbound call and returns an authorization pending response until user
authentication is approved by the authorization server. After approval, the policy injects the
exchanged access token into the `Authorization` header and forwards requests to the backend service.

While waiting for user authentication, the policy returns a `401 Unauthorized` response with the
following JSON body:

HTTP/1.1 401 Unauthorized Retry-After: 5 Content-Type: application/json

{   "error": "authorization\_pending",   "error\_description": "CIBA authorization flow initiated.
Downstream user authorization is in progress. Retry after the indicated interval." }

<!-- document id=cfb917be29d18bf6338ebf402a9453ea12150006ec9463ee0151de07a240391b url=/mulesoft/current/en-us/gateway/latest/policies-outbound-oauth-obo.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: oauth2, token exchange, on-behalf-of, obo, rfc 8693, api gateway, flex gateway, gateway, policy
---

# OAuth 2.0 OBO Credential Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 OBO Credential Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Exchanges incoming bearer tokens using OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of, or OAuth 2.0 Token Exchange with CIBA</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-obo-release-notes">OAuth 2.0 OBO Credential Injection</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## Summary

The OAuth 2.0 On-Behalf-Of (OBO) Credential Injection policy exchanges an incoming bearer token for
a new token to target specific upstream services. The policy supports OAuth 2.0 Token Exchange (RFC
8693), Microsoft Entra ID On-Behalf-Of protocols, and OAuth 2.0 Token Exchange with Client Initiated
Backchannel Authentication (CIBA). This policy is applied to outbound traffic (gateway to the
backend service) to automatically exchange the OAuth 2.0 token needed for backend services.

The policy extracts the Bearer token from the incoming request’s `Authorization` header and sends a
token exchange request to the token endpoint. The policy then replaces the `Authorization` header
with the new token returned from the token exchange service and forwards the modified request to the
backend service.

To avoid triggering multiple requests for identical tokens, successful token exchanges are cached.
By default, the cache only shares tokens between requests to the same replica. Enable distributed
caching to share tokens between Omni Replicas. To learn more, see
[Token Caching](#token-caching-oauth-obo).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The OAuth 2.0 OBO Credential Injection policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Token Exchange Flow</p></div></div></td><td><div><div><p>Token exchange flow: <strong>OAuth 2.0 Token Exchange</strong> (RFC 8693) or <strong>Microsoft Entra ID On-Behalf-Of</strong>.</p></div></div></td></tr><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p>OAuth 2.0 client ID for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Client Secret</p></div></div></td><td><div><div><p>OAuth 2.0 client secret for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>OAuth 2.0 token endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Target Type</p></div></div></td><td><div><div><p>Parameter type for specifying the target service. Required for OAuth 2.0 Token Exchange flow. Supported values:</p></div><div><ul><li><p>Audience: Logical identifier of the target service (default)</p></li><li><p>Resource: Physical URI of the target resource (RFC 8707)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Target Value</p></div></div></td><td><div><div><p>Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange flow.</p></div></div></td></tr><tr><td><div><div><p>Requested Token Type</p></div></div></td><td><div><div><p>The desired token type URI for the issued token. When omitted, the parameter is not sent and the authorization server selects the issued token type. OAuth 2.0 Token Exchange flow only.</p></div></div></td></tr><tr><td><div><div><p>Subject Token Type</p></div></div></td><td><div><div><p>The token type URI for the incoming subject token from the request <code>Authorization</code> header. By default <code>urn:ietf:params:oauth:token-type:access_token</code>. For JWT tokens, use <code>urn:ietf:params:oauth:token-type:jwt</code>. OAuth 2.0 Token Exchange flow only.</p></div></div></td></tr><tr><td><div><div><p>Scope</p></div></div></td><td><div><div><p>OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, <code>api://downstream-client-id/.default</code>) and OAuth2 Token Exchange with CIBA (for example, <code>openid</code>). Optional for OAuth 2.0 Token Exchange (RFC 8693).</p></div></div></td></tr><tr><td><div><div><p>Timeout</p></div></div></td><td><div><div><p>Timeout for token exchange requests in milliseconds. Default: 10000.</p></div></div></td></tr><tr><td><div><div><p>Enable CIBA</p></div></div></td><td><div><div><p>Enables OAuth 2.0 Token Exchange with CIBA flow. Available only for OAuth 2.0 Token Exchange.</p></div></div></td></tr><tr><td><div><div><p>CIBA Backchannel Endpoint</p></div></div></td><td><div><div><p>The backchannel authentication endpoint (<code>bc-authorize</code>) used to initiate the CIBA flow. Required when <strong>Enable CIBA</strong> is selected.</p></div></div></td></tr><tr><td><div><div><p>Login Hint Claim</p></div></div></td><td><div><div><p>JWT claim from the incoming subject token to send as <code>login_hint</code> in the CIBA request. If no hint is specified, <code>email</code> is used.</p></div></div></td></tr><tr><td><div><div><p>Binding Message</p></div></div></td><td><div><div><p>Optional human-readable message sent as <code>binding_message</code> in the CIBA request and displayed on the authentication device.</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache and CIBA request state are shared across Omni Gateway replicas. Enable this option when running more than one replica to avoid duplicate token exchanges or duplicate CIBA initiations.</p></div></div></td></tr></tbody></table>

## Token Caching

The policy stores each exchanged downstream access token and reuses it when later requests present
the same token. Cached entries are tied to a stable key and expire in line with the token’s
lifetime:

- **TTL**: Cache entry lifetime is derived from the exchanged token.

- If the policy cannot determine expiry, it skips caching for that response. If the policy cannot
  build a cache key, it performs the exchange without using the cache.

- When **Enable CIBA** is enabled, CIBA initiation and polling state, including the approved access
  token, is cached through the same mechanism.

## CIBA Behavior

When **Enable CIBA** is selected, the policy initiates a CIBA backchannel authentication request on
the first matching outbound call and returns an authorization pending response until user
authentication is approved by the authorization server. After approval, the policy injects the
exchanged access token into the `Authorization` header and forwards requests to the backend service.

While waiting for user authentication, the policy returns a `401 Unauthorized` response with the
following JSON body:

HTTP/1.1 401 Unauthorized Retry-After: 5 Content-Type: application/json

{   "error": "authorization\_pending",   "error\_description": "CIBA authorization flow initiated.
Downstream user authorization is in progress. Retry after the indicated interval." }

<!-- document id=14ec6e19b5aea7c3658b5a1025d8705a8b4c0551d575f5a9779b5b8c29b026e2 url=/mulesoft/current/en-us/gateway/1.13/policies-included-oauth-protected-resource-metadata.md -->

---
product: Omni Gateway
version: 1.13
keywords: oauth, protected resource, metadata, rfc 9728, api gateway, flex gateway, gateway, policy
---

# OAuth 2.0 Protected Resource Metadata Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 Protected Resource Metadata</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Serves OAuth 2.0 Protected Resource Metadata at the well-known endpoint</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-protected-resource-metadata-release-notes">OAuth 2.0 Protected Resource Metadata</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>404 - Request path does not match the well-known endpoint</p></td></tr><tr><td><p>405 - HTTP method is not GET</p></td></tr></tbody></table>

## Summary

The OAuth Protected Resource Metadata policy serves a JSON document describing the protected
resource’s OAuth 2.0 metadata at `/.well-known/oauth-protected-resource` as defined by
[RFC 9728](https://www.rfc-editor.org/rfc/rfc9728). The metadata document is defined by the policy.
The policy doesn’t fetch metadata from an external source.

This policy enables authorization servers and client applications to discover important OAuth 2.0
configuration details about your protected resource, such as:

- Which authorization server tokens are accepted

- What scopes are available for authorization

- How to send bearer tokens (header, body, or query)

- Whether DPoP or mTLS token binding is required

- What URLs are available for resource documentation, policy, and terms of service

> [!IMPORTANT] This policy rejects all requests that aren’t made to the
> `/.well-known/oauth-protected-resource` route with a `404 Not Found` response.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The OAuth 2.0 Protected Resource Metadata policy doesn’t support Omni Gateway running in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Resource Identifier</p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The protected resource identifier (RFC 8707). Must be an <code>https</code> URL without a fragment. This value is returned as the <code>resource</code> field in the metadata response and is used by clients to validate the response matches the resource they intended to query.<br>Example: <code>"https://api.example.com/v1"</code></p></div></div></td></tr><tr><td><div><div><p>Authorization Servers</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>Array of OAuth 2.0 authorization server issuer identifier URLs (per RFC 8414) whose tokens are accepted by this protected resource. Enter multiple values separated by commas or on separate lines.<br>Example: <code>["https://auth.example.com"]</code></p></div></div></td></tr><tr><td><div><div><p>JWK Set URI</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>URL of the resource’s JWK Set document containing its public keys for signing resource responses. Must use <code>https</code> scheme.<br>Example: <code>"https://api.example.com/.well-known/jwks.json"</code></p></div></div></td></tr><tr><td><div><div><p>Scopes Supported</p></div></div></td><td><div><div><p>Optional (recommended by RFC 9728)</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>Array of default OAuth 2.0 scope values that can be used to request access to this resource. This value is returned when the well-known path has no suffix or when the suffix doesn’t match any entry in Resource Scopes Overrides. Enter multiple values separated by commas or on separate lines.<br>Example: <code>["read", "write", "admin"]</code></p></div></div></td></tr><tr><td><div><div><p>Resource Scopes Overrides</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>[]</code> (no overrides)</p></div></div></td><td><div><div><p>Array of objects mapping per-resource-path overrides for <code>scopes_supported</code>. Each entry maps a path suffix to a specific set of scopes. When a client requests <code>/.well-known/oauth-protected-resource/&lt;suffix&gt;</code>, the policy looks for a matching entry; if found, the entry’s scopes replace the default Scopes Supported in the response.<br>Each object contains:<br><br>* <code>path</code> (string, required) - The path suffix to match. Matched case-sensitively against the portion of the request path after <code>/.well-known/oauth-protected-resource/</code>.<br>* <code>scopesSupported</code> (array of strings, required) - The scopes to return for this resource path.</p></div></div></td></tr><tr><td><div><div><p>Bearer Methods Supported</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>Array of methods supported for sending bearer access tokens. Defined values are <code>"header"</code>, <code>"body"</code>, and <code>"query"</code> (per RFC 6750 Sections 2.1-2.3). An empty array means no bearer token methods are supported.<br>Example: <code>["header"]</code></p></div></div></td></tr><tr><td><div><div><p>Resource Signing Algorithm Values</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>Array of JWS <code>alg</code> values the resource uses to sign responses.<br>Example: <code>["RS256", "ES256"]</code></p></div></div></td></tr><tr><td><div><div><p>Resource Name</p></div></div></td><td><div><div><p>Optional (recommended by RFC 9728)</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>Human-readable name of the protected resource, suitable for display to end users.<br>Example: <code>"Example API"</code></p></div></div></td></tr><tr><td><div><div><p>Resource Documentation URL</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>URL of a page containing human-readable developer documentation for the resource.<br>Example: <code>"https://docs.example.com/api"</code></p></div></div></td></tr><tr><td><div><div><p>Resource Policy URI</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>URL of a page describing the resource’s data-use policy for clients.<br>Example: <code>"https://example.com/privacy"</code></p></div></div></td></tr><tr><td><div><div><p>Resource Terms of Service URI</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>URL of a page with the resource’s terms of service.<br>Example: <code>"https://example.com/tos"</code></p></div></div></td></tr><tr><td><div><div><p>TLS Client Certificate Bound Access Tokens</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code> (omitted from response when <code>false</code>)</p></div></div></td><td><div><div><p>Boolean indicating whether the resource requires mutual-TLS certificate-bound access tokens (RFC 8705).</p></div></div></td></tr><tr><td><div><div><p>Authorization Details Types Supported</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>Array of authorization details <code>type</code> values the resource supports (RFC 9396).<br>Example: <code>["payment_initiation"]</code></p></div></div></td></tr><tr><td><div><div><p>DPoP Signing Algorithm Values</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>(omitted from response)</p></div></div></td><td><div><div><p>Array of JWS <code>alg</code> values the resource accepts for DPoP proof JWTs (RFC 9449).<br>Example: <code>["ES256"]</code></p></div></div></td></tr><tr><td><div><div><p>DPoP Bound Access Tokens Required</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code> (omitted from response when <code>false</code>)</p></div></div></td><td><div><div><p>Boolean indicating whether DPoP-bound access tokens are always required by this resource.</p></div></div></td></tr></tbody></table>

## Resource Configuration Examples

### Minimal Configuration

This example shows the minimum required configuration with basic scope and authorization server
information:

```yaml
- policyRef:
    name: oauth-protected-resource-metadata-policy-flex
  config:
    resource: "https://api.example.com"
    scopesSupported:
      - "read"
      - "write"
    authorizationServers:
      - "https://auth.example.com"
```

### Full Configuration

This example demonstrates all available configuration parameters:

```yaml
- policyRef:
    name: oauth-protected-resource-metadata-policy-flex
  config:
    resource: "https://api.example.com/v1"
    authorizationServers:
      - "https://auth.example.com"
      - "https://backup-auth.example.com"
    jwksUri: "https://api.example.com/.well-known/jwks.json"
    scopesSupported:
      - "read"
      - "write"
      - "admin"
    bearerMethodsSupported:
      - "header"
    resourceSigningAlgValuesSupported:
      - "RS256"
      - "ES256"
    resourceName: "Example API"
    resourceDocumentation: "https://docs.example.com/api"
    resourcePolicyUri: "https://example.com/privacy"
    resourceTosUri: "https://example.com/tos"
    tlsClientCertificateBoundAccessTokens: true
    authorizationDetailsTypesSupported:
      - "payment_initiation"
    dpopSigningAlgValuesSupported:
      - "ES256"
    dpopBoundAccessTokensRequired: true
```

### Per-Resource Scope Overrides

This example shows how to configure different scopes for different resource paths:

```yaml
- policyRef:
    name: oauth-protected-resource-metadata-policy-flex
  config:
    resource: "https://api.example.com"
    authorizationServers:
      - "https://auth.example.com"
    scopesSupported:
      - "read"
      - "write"
    resourceScopesOverrides:
      - path: "users"
        scopesSupported:
          - "users:read"
          - "users:write"
          - "users:delete"
      - path: "orders"
        scopesSupported:
          - "orders:read"
          - "orders:create"
```

## Request Processing

1.  **Path Matching:** The policy checks whether the request path ends with
    `/.well-known/oauth-protected-resource` or contains `/.well-known/oauth-protected-resource/`
    followed by a suffix. If the path doesn’t match, the policy returns `404 Not Found`.

2.  **Method Validation:** If the path matches but the HTTP method is not `GET`, the policy returns
    `405 Method Not Allowed` with an `Allow: GET` header.

3.  **Scope Resolution:** If the request path has a suffix after
    `/.well-known/oauth-protected-resource/`, the policy searches `resourceScopesOverrides` for an
    entry whose `path` matches the suffix exactly. If found, the entry’s `scopesSupported` replaces
    the top-level default in the response. If no override matches, the top-level `scopesSupported`
    is used.

4.  **Metadata Response:** For matching `GET` requests, the policy constructs a JSON object from the
    configured properties. For response examples, see [Example Responses](#example-responses).

## Property Mapping

The policy maps configuration parameters to JSON response fields using snake\_case naming:

<table><colgroup><col> <col></colgroup><thead><tr><th>Configuration Parameter</th><th>JSON Response Field</th></tr></thead><tbody><tr><td><div><div><p>Resource Identifier</p></div></div></td><td><div><div><p><code>resource</code></p></div></div></td></tr><tr><td><div><div><p>Authorization Servers</p></div></div></td><td><div><div><p><code>authorization_servers</code></p></div></div></td></tr><tr><td><div><div><p>JWK Set URI</p></div></div></td><td><div><div><p><code>jwks_uri</code></p></div></div></td></tr><tr><td><div><div><p>Scopes Supported</p></div></div></td><td><div><div><p><code>scopes_supported</code></p></div></div></td></tr><tr><td><div><div><p>Bearer Methods Supported</p></div></div></td><td><div><div><p><code>bearer_methods_supported</code></p></div></div></td></tr><tr><td><div><div><p>Resource Signing Algorithm Values</p></div></div></td><td><div><div><p><code>resource_signing_alg_values_supported</code></p></div></div></td></tr><tr><td><div><div><p>Resource Name</p></div></div></td><td><div><div><p><code>resource_name</code></p></div></div></td></tr><tr><td><div><div><p>Resource Documentation URL</p></div></div></td><td><div><div><p><code>resource_documentation</code></p></div></div></td></tr><tr><td><div><div><p>Resource Policy URI</p></div></div></td><td><div><div><p><code>resource_policy_uri</code></p></div></div></td></tr><tr><td><div><div><p>Resource Terms of Service URI</p></div></div></td><td><div><div><p><code>resource_tos_uri</code></p></div></div></td></tr><tr><td><div><div><p>TLS Client Certificate Bound Access Tokens</p></div></div></td><td><div><div><p><code>tls_client_certificate_bound_access_tokens</code></p></div></div></td></tr><tr><td><div><div><p>Authorization Details Types Supported</p></div></div></td><td><div><div><p><code>authorization_details_types_supported</code></p></div></div></td></tr><tr><td><div><div><p>DPoP Signing Algorithm Values</p></div></div></td><td><div><div><p><code>dpop_signing_alg_values_supported</code></p></div></div></td></tr><tr><td><div><div><p>DPoP Bound Access Tokens Required</p></div></div></td><td><div><div><p><code>dpop_bound_access_tokens_required</code></p></div></div></td></tr></tbody></table>

## Example Responses

These examples show the JSON metadata document the policy returns for a `GET` request to the
well-known endpoint.

### Minimal Configuration Response

When only `resource`, `authorizationServers`, and `scopesSupported` are configured, a `GET` request
to `/.well-known/oauth-protected-resource` returns:

```json
{
  "resource": "https://api.example.com",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["read", "write"]
}
```

### Full Configuration Response

When all parameters are configured, a `GET` request to `/.well-known/oauth-protected-resource`
returns all configured fields:

```json
{
  "resource": "https://api.example.com/v1",
  "authorization_servers": ["https://auth.example.com", "https://backup-auth.example.com"],
  "jwks_uri": "https://api.example.com/.well-known/jwks.json",
  "scopes_supported": ["read", "write", "admin"],
  "bearer_methods_supported": ["header"],
  "resource_signing_alg_values_supported": ["RS256", "ES256"],
  "resource_name": "Example API",
  "resource_documentation": "https://docs.example.com/api",
  "resource_policy_uri": "https://example.com/privacy",
  "resource_tos_uri": "https://example.com/tos",
  "tls_client_certificate_bound_access_tokens": true,
  "authorization_details_types_supported": ["payment_initiation"],
  "dpop_signing_alg_values_supported": ["ES256"],
  "dpop_bound_access_tokens_required": true
}
```

### Per-Resource Scope Overrides Responses

When `resourceScopesOverrides` maps the `users` path suffix to
`["users:read", "users:write", "users:delete"]` over a top-level default of `["read", "write"]`:

- A `GET` request to the default endpoint, `/.well-known/oauth-protected-resource`, returns the
  top-level scopes:

  ```json
  {
    "resource": "https://api.example.com",
    "authorization_servers": ["https://auth.example.com"],
    "scopes_supported": ["read", "write"]
  }
  ```

- A `GET` request to `/.well-known/oauth-protected-resource/users` matches the `users` override and
  returns its scopes:

  ```json
  {
    "resource": "https://api.example.com",
    "authorization_servers": ["https://auth.example.com"],
    "scopes_supported": ["users:read", "users:write", "users:delete"]
  }
  ```

- A `GET` request to an unconfigured suffix, such as
  `/.well-known/oauth-protected-resource/billing`, falls back to the top-level scopes:

  ```json
  {
    "resource": "https://api.example.com",
    "authorization_servers": ["https://auth.example.com"],
    "scopes_supported": ["read", "write"]
  }
  ```

## Edge Cases

- **Non-matching paths:** Any request whose path doesn’t contain
  `/.well-known/oauth-protected-resource` receives `404 Not Found`. The policy is intended to be
  route-scoped to the well-known path.

- **Trailing slash:** `/.well-known/oauth-protected-resource/` (with trailing slash) is treated as a
  match with an empty suffix. Since an empty string won’t match any `resourceScopesOverrides`
  entries, the top-level `scopesSupported` is returned.

- **Case sensitivity:** Path matching is case-sensitive per RFC 9728 and RFC 8615.

- **Query parameters:** Query strings on the well-known URL are ignored (the path is matched without
  query or fragment).

- **Empty `bearerMethodsSupported`:** An explicitly configured empty array `[]` is serialized in the
  response (it signals "no bearer methods supported"), distinct from omitting the field entirely.

<!-- document id=2bbd35bf95fba662c8a0cc465701082072464f38876c081a3edeaef520f3d7cb url=/mulesoft/current/en-us/gateway/latest/policies-included-oauth-protected-resource-metadata.md -->

# OAuth 2.0 Protected Resource Metadata Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">OAuth 2.0 Protected Resource Metadata</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Serves OAuth 2.0 Protected Resource Metadata at the well-known endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Security</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.13.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-protected-resource-metadata-release-notes" class="xref page">OAuth 2.0 Protected Resource Metadata</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle" rowspan="4"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">404 - Request path does not match the well-known endpoint</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">405 - HTTP method is not GET</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">400 - Registration request matches no configured client (<a href="#static-dynamic-client-registration">Static Dynamic Client Registration</a> only)</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The OAuth Protected Resource Metadata policy serves a JSON document describing the protected resource’s OAuth 2.0 metadata at `/.well-known/oauth-protected-resource` as defined by [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728).

This policy enables authorization servers and client applications to discover important OAuth 2.0 configuration details about your protected resource, such as:

- Which authorization server tokens are accepted
- What scopes are available for authorization
- How to send bearer tokens (header, body, or query)
- Whether DPoP or mTLS token binding is required
- What URLs are available for resource documentation, policy, and terms of service

For identity providers (IdP) that don’t support support Dynamic Client Registration (DCR), the policy provides [Static DCR configuration](#static-dynamic-client-registration). Use it when your MCP clients require a `registration_endpoint`, but your IdP doesn’t support DCR. If your IdP supports DCR, or clients only need to discover your authorization server and scopes, static DCR configuration isn’t required.

<table><tbody><tr><td class="icon"><i class="fa icon-important" title="Important"></i></td><td class="content">This policy rejects all requests that aren’t made to the <code>/.well-known/oauth-protected-resource</code> route with a <code>404 Not Found</code> response.</td></tr></tbody></table>

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#omni-gateway-local-mode)Omni Gateway Local Mode

The OAuth 2.0 Protected Resource Metadata policy doesn’t support Omni Gateway running in Local Mode.

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Identifier</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The protected resource identifier (RFC 8707). Must be an <code>https</code> URL without a fragment. This value is returned as the <code>resource</code> field in the metadata response and is used by clients to validate the response matches the resource they intended to query.<br>
Example: <code>"https://api.example.com/v1"</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Authorization Servers</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of OAuth 2.0 authorization server issuer identifier URLs (per RFC 8414) whose tokens are accepted by this protected resource. Enter multiple values separated by commas or on separate lines.<br>
If you enable Static Dynamic Client Registration, these are the upstream servers whose metadata the policy fetches, and the response advertises the Consumer URL instead.<br>
Example: <code>["https://auth.example.com"]</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>JWK Set URI</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>URL of the resource’s JWK Set document containing its public keys for signing resource responses. Must use <code>https</code> scheme.<br>
Example: <code>"https://api.example.com/.well-known/jwks.json"</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Scopes Supported</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional (recommended by RFC 9728)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of default OAuth 2.0 scope values that can be used to request access to this resource. This value is returned when the well-known path has no suffix or when the suffix doesn’t match any entry in Resource Scopes Overrides. Enter multiple values separated by commas or on separate lines.<br>
Example: <code>["read", "write", "admin"]</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Scopes Overrides</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>[]</code> (no overrides)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of objects mapping per-resource-path overrides for <code>scopes_supported</code>. Each entry maps a path suffix to a specific set of scopes. When a client requests <code>/.well-known/oauth-protected-resource/&lt;suffix&gt;</code>, the policy looks for a matching entry; if found, the entry’s scopes replace the default Scopes Supported in the response.<br>
Each object contains:<br>
<br>
* <code>path</code> (string, required) - The path suffix to match. Matched case-sensitively against the portion of the request path after <code>/.well-known/oauth-protected-resource/</code>.<br>
* <code>scopesSupported</code> (array of strings, required) - The scopes to return for this resource path.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Bearer Methods Supported</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of methods supported for sending bearer access tokens. Defined values are <code>"header"</code>, <code>"body"</code>, and <code>"query"</code> (per RFC 6750 Sections 2.1-2.3). An empty array means no bearer token methods are supported.<br>
Example: <code>["header"]</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Signing Algorithm Values</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of JWS <code>alg</code> values the resource uses to sign responses.<br>
Example: <code>["RS256", "ES256"]</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Name</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional (recommended by RFC 9728)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Human-readable name of the protected resource, suitable for display to end users.<br>
Example: <code>"Example API"</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Documentation URL</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>URL of a page containing human-readable developer documentation for the resource.<br>
Example: <code>"https://docs.example.com/api"</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Policy URI</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>URL of a page describing the resource’s data-use policy for clients.<br>
Example: <code>"https://example.com/privacy"</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Terms of Service URI</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>URL of a page with the resource’s terms of service.<br>
Example: <code>"https://example.com/tos"</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>TLS Client Certificate Bound Access Tokens</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code> (omitted from response when <code>false</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean indicating whether the resource requires mutual-TLS certificate-bound access tokens (RFC 8705).</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Authorization Details Types Supported</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of authorization details <code>type</code> values the resource supports (RFC 9396).<br>
Example: <code>["payment_initiation"]</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DPoP Signing Algorithm Values</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(omitted from response)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of JWS <code>alg</code> values the resource accepts for DPoP proof JWTs (RFC 9449).<br>
Example: <code>["ES256"]</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DPoP Bound Access Tokens Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code> (omitted from response when <code>false</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean indicating whether DPoP-bound access tokens are always required by this resource.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Static Dynamic Client Registration</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>(disabled)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Object that makes an identity provider without Dynamic Client Registration (DCR) support appear DCR-capable to MCP clients. For the fields and behavior, see <a href="#static-dynamic-client-registration">Static Dynamic Client Registration</a>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#resource-configuration-examples)Resource Configuration Examples

### [](#minimal-configuration)Minimal Configuration

This example shows the minimum required configuration with basic scope and authorization server information:

```yaml
- policyRef:
    name: oauth-protected-resource-metadata-policy-flex
  config:
    resource: "https://api.example.com"
    scopesSupported:
      - "read"
      - "write"
    authorizationServers:
      - "https://auth.example.com"
```

### [](#full-configuration)Full Configuration

This example demonstrates all available configuration parameters:

```yaml
- policyRef:
    name: oauth-protected-resource-metadata-policy-flex
  config:
    resource: "https://api.example.com/v1"
    authorizationServers:
      - "https://auth.example.com"
      - "https://backup-auth.example.com"
    jwksUri: "https://api.example.com/.well-known/jwks.json"
    scopesSupported:
      - "read"
      - "write"
      - "admin"
    bearerMethodsSupported:
      - "header"
    resourceSigningAlgValuesSupported:
      - "RS256"
      - "ES256"
    resourceName: "Example API"
    resourceDocumentation: "https://docs.example.com/api"
    resourcePolicyUri: "https://example.com/privacy"
    resourceTosUri: "https://example.com/tos"
    tlsClientCertificateBoundAccessTokens: true
    authorizationDetailsTypesSupported:
      - "payment_initiation"
    dpopSigningAlgValuesSupported:
      - "ES256"
    dpopBoundAccessTokensRequired: true
```

### [](#per-resource-scope-overrides)Per-Resource Scope Overrides

This example shows how to configure different scopes for different resource paths:

```yaml
- policyRef:
    name: oauth-protected-resource-metadata-policy-flex
  config:
    resource: "https://api.example.com"
    authorizationServers:
      - "https://auth.example.com"
    scopesSupported:
      - "read"
      - "write"
    resourceScopesOverrides:
      - path: "users"
        scopesSupported:
          - "users:read"
          - "users:write"
          - "users:delete"
      - path: "orders"
        scopesSupported:
          - "orders:read"
          - "orders:create"
```

## [](#static-dynamic-client-registration)Static Dynamic Client Registration

MCP clients register with an authorization server through its `registration_endpoint` ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)). If your IdP doesn’t support DCR, there is no `registration_endpoint`, and MCP clients can’t complete the OAuth flow.

When you enable Static Dynamic Client Registration, the policy:

- Advertises the gateway’s public URL (the Consumer URL) as the authorization server.
- Serves the IdP’s authorization server metadata with a `registration_endpoint` that points at the gateway.
- Serves that endpoint at `/.well-known/idp/register`. It returns the credentials of a client you already created in the IdP, chosen by matching the request’s `client_name`.

The IdP still authorizes users and issues tokens.

<table><tbody><tr><td class="icon"><i class="fa icon-important" title="Important"></i></td><td class="content">All MCP clients that match the same entry receive the same <code>client_id</code> and <code>client_secret</code>. Use public clients without a secret, or trusted MCP clients, and limit what the client can access in the IdP.</td></tr></tbody></table>

### [](#static-dcr-parameters)Parameters

Configure these parameters under **Static Dynamic Client Registration** (`staticDcr`). You must also set Authorization Servers.

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Enable (<code>enabled</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Turns the feature on.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Authorization Server Metadata Path (<code>authorizationServerMetadataPath</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>/.well-known/oauth-authorization-server</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Path of the authorization server metadata. For OpenID Connect IdPs, use <code>/.well-known/openid-configuration</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Consumer URL (<code>consumerUrl</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Taken from API Manager</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Public URL clients use to reach this API.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Static DCR Clients (<code>clients</code>)</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of preconfigured clients. The policy uses the first entry whose <code>name</code> matches the request’s <code>client_name</code>. If none match, the request is rejected. Each entry contains:<br>
<br>
* <code>name</code> (required) - Case-insensitive match on <code>client_name</code>. Use <code><strong></strong></code><strong> as a wildcard at the start or end, such as <code>claude</code></strong>. Use <code>*</code> alone to match any name.<br>
* <code>clientId</code> (required) - The client ID to return.<br>
* <code>clientSecret</code> (optional) - The client secret to return. Omit it for public clients.</p>
</div></div></td>
</tr>
</tbody>
</table>

### [](#static-dcr-configuration-example)Static DCR Configuration Example

```yaml
- policyRef:
    name: oauth-protected-resource-metadata-policy-flex
  config:
    resource: "https://api.example.com"
    authorizationServers:
      - "https://idp.example.com"
    staticDcr:
      enabled: true
      consumerUrl: "https://api.example.com"
      clients:
        - name: "claude*"
          clientId: "claude-mcp-client"
          clientSecret: "<CLAUDE_CLIENT_SECRET>"
        - name: "*"
          clientId: "shared-mcp-client"
```

### [](#static-dcr-walkthrough)Static DCR MCP Client Flow

First, create the OAuth clients in your IdP and apply the policy as shown in the example. Then an MCP client does the following:

1. Requests `/.well-known/oauth-protected-resource`. The policy returns the gateway as the authorization server:
    
    ```json
    {
      "resource": "https://api.example.com",
      "authorization_servers": ["https://api.example.com/"]
    }
    ```
2. Requests `/.well-known/oauth-authorization-server`. The policy returns the IdP’s metadata with the gateway’s `registration_endpoint`:
    
    ```json
    {
      "issuer": "https://idp.example.com",
      "authorization_endpoint": "https://idp.example.com/authorize",
      "token_endpoint": "https://idp.example.com/token",
      "registration_endpoint": "https://api.example.com/.well-known/idp/register"
    }
    ```
3. Sends a registration request to `/.well-known/idp/register`:
    
    ```json
    {
      "client_name": "Claude Desktop",
      "redirect_uris": ["https://client.example.com/callback"]
    }
    ```
    
    The name matches `claude*`, so the policy returns `201 Created` with that client’s credentials:
    
    ```json
    {
      "client_id": "claude-mcp-client",
      "client_secret": "<CLAUDE_CLIENT_SECRET>",
      "client_secret_expires_at": 0,
      "client_id_issued_at": 1719360000,
      "client_name": "Claude Desktop",
      "redirect_uris": ["https://client.example.com/callback"]
    }
    ```
4. Signs the user in directly with the IdP using the returned `client_id`, then calls the API with the access token.

If no entry matches the `client_name`, the policy returns `400 Bad Request` with the error `invalid_client_metadata`.

The policy fetches the IdP’s metadata on every authorization server metadata request and doesn’t cache it. If the policy can’t reach any IdP, the request returns `502 Bad Gateway`. The registration endpoint doesn’t depend on the IdP.

## [](#request-processing)Request Processing

1. **Path Matching:** The policy checks whether the request path ends with `/.well-known/oauth-protected-resource` or contains `/.well-known/oauth-protected-resource/` followed by a suffix. If the path doesn’t match, the policy returns `404 Not Found`.
2. **Method Validation:** If the path matches but the HTTP method is not `GET`, the policy returns `405 Method Not Allowed` with an `Allow: GET` header.
3. **Scope Resolution:** If the request path has a suffix after `/.well-known/oauth-protected-resource/`, the policy searches `resourceScopesOverrides` for an entry whose `path` matches the suffix exactly. If found, the entry’s `scopesSupported` replaces the top-level default in the response. If no override matches, the top-level `scopesSupported` is used.
4. **Metadata Response:** For matching `GET` requests, the policy constructs a JSON object from the configured properties. For response examples, see [Example Responses](#example-responses).

## [](#property-mapping)Property Mapping

The policy maps configuration parameters to JSON response fields using snake\_case naming:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Configuration Parameter</th>
<th class="tableblock halign-left valign-top">JSON Response Field</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Identifier</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>resource</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Authorization Servers</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>authorization_servers</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>JWK Set URI</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>jwks_uri</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Scopes Supported</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>scopes_supported</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Bearer Methods Supported</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>bearer_methods_supported</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Signing Algorithm Values</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>resource_signing_alg_values_supported</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Name</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>resource_name</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Documentation URL</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>resource_documentation</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Policy URI</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>resource_policy_uri</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Resource Terms of Service URI</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>resource_tos_uri</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>TLS Client Certificate Bound Access Tokens</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>tls_client_certificate_bound_access_tokens</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Authorization Details Types Supported</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>authorization_details_types_supported</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DPoP Signing Algorithm Values</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>dpop_signing_alg_values_supported</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DPoP Bound Access Tokens Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>dpop_bound_access_tokens_required</code></p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#example-responses)Example Responses

These examples show the JSON metadata document the policy returns for a `GET` request to the well-known endpoint.

### [](#minimal-configuration-response)Minimal Configuration Response

When only `resource`, `authorizationServers`, and `scopesSupported` are configured, a `GET` request to `/.well-known/oauth-protected-resource` returns:

```json
{
  "resource": "https://api.example.com",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["read", "write"]
}
```

### [](#full-configuration-response)Full Configuration Response

When all parameters are configured, a `GET` request to `/.well-known/oauth-protected-resource` returns all configured fields:

```json
{
  "resource": "https://api.example.com/v1",
  "authorization_servers": ["https://auth.example.com", "https://backup-auth.example.com"],
  "jwks_uri": "https://api.example.com/.well-known/jwks.json",
  "scopes_supported": ["read", "write", "admin"],
  "bearer_methods_supported": ["header"],
  "resource_signing_alg_values_supported": ["RS256", "ES256"],
  "resource_name": "Example API",
  "resource_documentation": "https://docs.example.com/api",
  "resource_policy_uri": "https://example.com/privacy",
  "resource_tos_uri": "https://example.com/tos",
  "tls_client_certificate_bound_access_tokens": true,
  "authorization_details_types_supported": ["payment_initiation"],
  "dpop_signing_alg_values_supported": ["ES256"],
  "dpop_bound_access_tokens_required": true
}
```

### [](#per-resource-scope-overrides-response)Per-Resource Scope Overrides Responses

When `resourceScopesOverrides` maps the `users` path suffix to `["users:read", "users:write", "users:delete"]` over a top-level default of `["read", "write"]`:

- A `GET` request to the default endpoint, `/.well-known/oauth-protected-resource`, returns the top-level scopes:
    
    ```json
    {
      "resource": "https://api.example.com",
      "authorization_servers": ["https://auth.example.com"],
      "scopes_supported": ["read", "write"]
    }
    ```
- A `GET` request to `/.well-known/oauth-protected-resource/users` matches the `users` override and returns its scopes:
    
    ```json
    {
      "resource": "https://api.example.com",
      "authorization_servers": ["https://auth.example.com"],
      "scopes_supported": ["users:read", "users:write", "users:delete"]
    }
    ```
- A `GET` request to an unconfigured suffix, such as `/.well-known/oauth-protected-resource/billing`, falls back to the top-level scopes:
    
    ```json
    {
      "resource": "https://api.example.com",
      "authorization_servers": ["https://auth.example.com"],
      "scopes_supported": ["read", "write"]
    }
    ```

## [](#edge-cases)Edge Cases

- **Non-matching paths:** Any request whose path doesn’t contain `/.well-known/oauth-protected-resource` receives `404 Not Found`. The policy is intended to be route-scoped to the well-known path.
- **Trailing slash:** `/.well-known/oauth-protected-resource/` (with trailing slash) is treated as a match with an empty suffix. Since an empty string won’t match any `resourceScopesOverrides` entries, the top-level `scopesSupported` is returned.
- **Case sensitivity:** Path matching is case-sensitive per RFC 9728 and RFC 8615.
- **Query parameters:** Query strings on the well-known URL are ignored (the path is matched without query or fragment).
- **Empty `bearerMethodsSupported`:** An explicitly configured empty array `[]` is serialized in the response (it signals "no bearer methods supported"), distinct from omitting the field entirely.

<!-- document id=24fbf288a8a23e6276fe1d1e6a00a8d16ac22d6e56537bf133622582de52ff48 url=/mulesoft/current/en-us/gateway/1.12/policies-included-oauth-token-introspection.md -->

---
product: Omni Gateway
version: 1.12
keywords: oauth, token, validation, introspection, policy
---

# OAuth 2.0 Token Introspection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 Token Introspection Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.3.0</p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP fault error</p></td></tr></tbody></table>

## Summary

The OAuth 2.0 Token Introspection policy enables you to configure OAuth 2.0 using any third-party
Identify Provider (IdP), such as Okta, AWS, Azure or Google Cloud Platform. The policy allows for
tokens based on the OAuth 2.0 Authorization Framework to be authorized without having to register an
external IdP server in the Anypoint Platform.

The policy validates the token sent by the client to the protected API, and allows access to the
backend server only if the introspection endpoint authorizes the token.

> [!NOTE] OAuth Introspection Policy doesn’t support Microsoft Entra ID because Microsoft Entra ID
> doesn’t provide an introspection endpoint.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: oauth2-token-introspection-flex config: introspectionURL: <string> // REQUIRED
authorizationValue: <string> // REQUIRED validatedTokenTTL: <number> // OPTIONAL
authenticationTimeout: <number> // OPTIONAL skipClientIdValidation: <boolean> // REQUIRED
consumerBy: <string> // REQUIRED exposeHeaders: <boolean> // OPTIONAL scopes: <string> // OPTIONAL
scopeValidationCriteria: <string> // OPTIONAL maxCacheEntries: <number> // OPTIONAL
enableProtectedResourceMetadata: <boolean> // OPTIONAL
overrideProtectedResourceMetadataAuthorizationServerUrl: <boolean> // OPTIONAL
protectedResourceMetadataAuthorizationServerUrl: <string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>introspectionURL</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The third-party token introspection URL</p></div></div></td></tr><tr><td><div><div><p><code>authorizationValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The method to request authorization from the authentication service. Specify either a Basic Auth string with <code>client_id</code> and <code>client_secret</code>, or a Bearer Token.</p></div></div></td></tr><tr><td><div><div><p><code>validatedTokenTTL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>The caching limit for the validated token</p></div></div></td></tr><tr><td><div><div><p><code>authenticationTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>The timeout when sending data to the authentication service</p></div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables client ID enforcement support</p></div></div></td></tr><tr><td><div><div><p><code>consumerBy</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>Associate an identity provider’s <code>username</code> or <code>client_id</code> response with a registered platform’s <code>client_id</code>. Required if <code>skip_client_id_validation`is `true</code>.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>scopes</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div><div><p>A space-delimited list</p></div></div></td></tr><tr><td><div><div><p><code>scopeValidationCriteria</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"AND"</p></div></div></td><td><div><div><p>The criteria to apply to the <code>scopes</code> values. Valid parameter values are "AND" or "OR".</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>enableProtectedResourceMetadata</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables <a href="https://www.rfc-editor.org/rfc/rfc9728">RFC 9728</a> OAuth 2.0 Protected Resource Metadata. When <code>true</code>, all <code>401</code> responses include a <code>WWW-Authenticate</code> header with the resource metadata URL <code>{api_path}/.well-known/oauth-protected-resource</code>.<br>When a client makes a GET request to this path, Flex Gateway responds with a JSON document containing the authorization server metadata. By default, Flex Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, <code><a href="https://auth.example.com/introspect">https://auth.example.com/introspect</a></code> becomes <code><a href="https://auth.example.com">https://auth.example.com</a></code>.</p></div></div></td></tr><tr><td><div><div><p><code>overrideProtectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.</p></div></div></td></tr><tr><td><div><div><p><code>protectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div></div></td><td><div><div><p>Server base URL to use when <code>overrideProtectedResourceMetadataAuthorizationServerUrl</code> is <code>true</code>.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: oauth2-token-introspection-flex
  config:
    introspectionURL: https://my-introspection.com/introspect
    authorizationValue: Basic am9obkBleGFtcGxlLmNvbTphYmMxMjM=
    validatedTokenTTL: 600
    authenticationTimeout: 10000
    skipClientIdValidation: false
    consumerBy: "client_id"
    exposeHeaders: true
    scopes: "profile email shopping"
    scopeValidationCriteria: "AND"
    maxCacheEntries: 1000
```

<!-- document id=ade9ec1d214c112e080b671cd748db6fa1baef62d59c599bb3bd3da93eb73ef8 url=/mulesoft/current/en-us/gateway/1.13/policies-included-oauth-token-introspection.md -->

---
product: Omni Gateway
version: 1.13
keywords: oauth, token, validation, introspection, policy
---

# OAuth 2.0 Token Introspection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 Token Introspection Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.3.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-token-introspection-release-notes">OAuth 2.0 Token Introspection Policy</a></p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP fault error</p></td></tr></tbody></table>

## Summary

The OAuth 2.0 Token Introspection policy enables you to configure OAuth 2.0 using any third-party
Identify Provider (IdP), such as Okta, AWS, Azure or Google Cloud Platform. The policy allows for
tokens based on the OAuth 2.0 Authorization Framework to be authorized without having to register an
external IdP server in the Anypoint Platform.

The policy validates the token sent by the client to the protected API, and allows access to the
backend server only if the introspection endpoint authorizes the token.

> [!NOTE] OAuth Introspection Policy doesn’t support Microsoft Entra ID because Microsoft Entra ID
> doesn’t provide an introspection endpoint.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: oauth2-token-introspection-flex config: introspectionURL: <string> // REQUIRED
authorizationValue: <string> // REQUIRED validatedTokenTTL: <number> // OPTIONAL
authenticationTimeout: <number> // OPTIONAL skipClientIdValidation: <boolean> // REQUIRED
consumerBy: <string> // REQUIRED exposeHeaders: <boolean> // OPTIONAL scopes: <string> // OPTIONAL
scopeValidationCriteria: <string> // OPTIONAL maxCacheEntries: <number> // OPTIONAL
enableProtectedResourceMetadata: <boolean> // OPTIONAL
overrideProtectedResourceMetadataAuthorizationServerUrl: <boolean> // OPTIONAL
protectedResourceMetadataAuthorizationServerUrl: <string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>introspectionURL</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The third-party token introspection URL</p></div></div></td></tr><tr><td><div><div><p><code>authorizationValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The method to request authorization from the authentication service. Specify either a Basic Auth string with <code>client_id</code> and <code>client_secret</code>, or a Bearer Token.</p></div></div></td></tr><tr><td><div><div><p><code>validatedTokenTTL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>The caching limit for the validated token</p></div></div></td></tr><tr><td><div><div><p><code>authenticationTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>The timeout when sending data to the authentication service</p></div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables client ID enforcement support</p></div></div></td></tr><tr><td><div><div><p><code>consumerBy</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>Associate an identity provider’s <code>username</code> or <code>client_id</code> response with a registered platform’s <code>client_id</code>. Required if <code>skip_client_id_validation`is `true</code>.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>scopes</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div><div><p>A space-delimited list</p></div></div></td></tr><tr><td><div><div><p><code>scopeValidationCriteria</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"AND"</p></div></div></td><td><div><div><p>The criteria to apply to the <code>scopes</code> values. Valid parameter values are "AND" or "OR".</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>enableProtectedResourceMetadata</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables <a href="https://www.rfc-editor.org/rfc/rfc9728">RFC 9728</a> OAuth 2.0 Protected Resource Metadata. When <code>true</code>, all <code>401</code> responses include a <code>WWW-Authenticate</code> header with the resource metadata URL <code>{api_path}/.well-known/oauth-protected-resource</code>.<br>When a client makes a GET request to this path, Omni Gateway responds with a JSON document containing the authorization server metadata. By default, Omni Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, <code><a href="https://auth.example.com/introspect">https://auth.example.com/introspect</a></code> becomes <code><a href="https://auth.example.com">https://auth.example.com</a></code>.</p></div></div></td></tr><tr><td><div><div><p><code>overrideProtectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.</p></div></div></td></tr><tr><td><div><div><p><code>protectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div></div></td><td><div><div><p>Server base URL to use when <code>overrideProtectedResourceMetadataAuthorizationServerUrl</code> is <code>true</code>.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: oauth2-token-introspection-flex
  config:
    introspectionURL: https://my-introspection.com/introspect
    authorizationValue: Basic am9obkBleGFtcGxlLmNvbTphYmMxMjM=
    validatedTokenTTL: 600
    authenticationTimeout: 10000
    skipClientIdValidation: false
    consumerBy: "client_id"
    exposeHeaders: true
    scopes: "profile email shopping"
    scopeValidationCriteria: "AND"
    maxCacheEntries: 1000
```

<!-- document id=428d1b32ff6f6eb9d0fdd6499fd9254d22b6d66e06b25a44bd40b995910d7b80 url=/mulesoft/current/en-us/gateway/1.9/policies-included-oauth-token-introspection.md -->

---
product: Omni Gateway
version: 1.9
keywords: oauth, token, validation, introspection, policy
---

# OAuth 2.0 Token Introspection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 Token Introspection Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.3.0</p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP fault error</p></td></tr></tbody></table>

## Summary

The OAuth 2.0 Token Introspection policy enables you to configure OAuth 2.0 using any third-party
Identify Provider (IdP), such as Okta, AWS, Azure or Google Cloud Platform. The policy allows for
tokens based on the OAuth 2.0 Authorization Framework to be authorized without having to register an
external IdP server in the Anypoint Platform.

The policy validates the token sent by the client to the protected API, and allows access to the
backend server only if the introspection endpoint authorizes the token.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: oauth2-token-introspection-flex config: introspectionURL: <string> // REQUIRED
authorizationValue: <string> // REQUIRED validatedTokenTTL: <number> // OPTIONAL
authenticationTimeout: <number> // OPTIONAL skipClientIdValidation: <boolean> // REQUIRED
consumerBy: <string> // REQUIRED exposeHeaders: <boolean> // OPTIONAL scopes: <string> // OPTIONAL
scopeValidationCriteria: <string> // OPTIONAL maxCacheEntries: <number> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>introspectionURL</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The third-party token introspection URL</p></div></div></td></tr><tr><td><div><div><p><code>authorizationValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The method to request authorization from the authentication service. Specify either a Basic Auth string with <code>client_id</code> and <code>client_secret</code>, or a Bearer Token.</p></div></div></td></tr><tr><td><div><div><p><code>validatedTokenTTL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>The caching limit for the validated token</p></div></div></td></tr><tr><td><div><div><p><code>authenticationTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>The timeout when sending data to the authentication service</p></div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables client ID enforcement support</p></div></div></td></tr><tr><td><div><div><p><code>consumerBy</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>Associate an identity provider’s <code>username</code> or <code>client_id</code> response with a registered platform’s <code>client_id</code>. Required if <code>skip_client_id_validation`is `true</code>.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>scopes</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div><div><p>A space-delimited list</p></div></div></td></tr><tr><td><div><div><p><code>scopeValidationCriteria</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"AND"</p></div></div></td><td><div><div><p>The criteria to apply to the <code>scopes</code> values. Valid parameter values are "AND" or "OR".</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: oauth2-token-introspection-flex
  config:
    introspectionURL: https://my-introspection.com/introspect
    authorizationValue: Basic am9obkBleGFtcGxlLmNvbTphYmMxMjM=
    validatedTokenTTL: 600
    authenticationTimeout: 10000
    skipClientIdValidation: false
    consumerBy: "client_id"
    exposeHeaders: true
    scopes: "profile email shopping"
    scopeValidationCriteria: "AND"
    maxCacheEntries: 1000
```

<!-- document id=f35a977cd4c27a0a3d9763b819bfce47871b563f39c99b4d76d7ee2a3cf475b4 url=/mulesoft/current/en-us/gateway/latest/policies-included-oauth-token-introspection.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: oauth, token, validation, introspection, policy
---

# OAuth 2.0 Token Introspection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 Token Introspection Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.3.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-token-introspection-release-notes">OAuth 2.0 Token Introspection Policy</a></p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server, or WSDL SOAP fault error</p></td></tr></tbody></table>

## Summary

The OAuth 2.0 Token Introspection policy enables you to configure OAuth 2.0 using any third-party
Identify Provider (IdP), such as Okta, AWS, Azure or Google Cloud Platform. The policy allows for
tokens based on the OAuth 2.0 Authorization Framework to be authorized without having to register an
external IdP server in the Anypoint Platform.

The policy validates the token sent by the client to the protected API, and allows access to the
backend server only if the introspection endpoint authorizes the token.

> [!NOTE] OAuth Introspection Policy doesn’t support Microsoft Entra ID because Microsoft Entra ID
> doesn’t provide an introspection endpoint.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: oauth2-token-introspection-flex config: introspectionURL: <string> // REQUIRED
authorizationValue: <string> // REQUIRED validatedTokenTTL: <number> // OPTIONAL
authenticationTimeout: <number> // OPTIONAL skipClientIdValidation: <boolean> // REQUIRED
consumerBy: <string> // REQUIRED exposeHeaders: <boolean> // OPTIONAL scopes: <string> // OPTIONAL
scopeValidationCriteria: <string> // OPTIONAL maxCacheEntries: <number> // OPTIONAL
enableProtectedResourceMetadata: <boolean> // OPTIONAL
overrideProtectedResourceMetadataAuthorizationServerUrl: <boolean> // OPTIONAL
protectedResourceMetadataAuthorizationServerUrl: <string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>introspectionURL</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The third-party token introspection URL</p></div></div></td></tr><tr><td><div><div><p><code>authorizationValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The method to request authorization from the authentication service. Specify either a Basic Auth string with <code>client_id</code> and <code>client_secret</code>, or a Bearer Token.</p></div></div></td></tr><tr><td><div><div><p><code>validatedTokenTTL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>The caching limit for the validated token</p></div></div></td></tr><tr><td><div><div><p><code>authenticationTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>The timeout when sending data to the authentication service</p></div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables client ID enforcement support</p></div></div></td></tr><tr><td><div><div><p><code>consumerBy</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>Associate an identity provider’s <code>username</code> or <code>client_id</code> response with a registered platform’s <code>client_id</code>. Required if <code>skip_client_id_validation`is `true</code>.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>scopes</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div><div><p>A space-delimited list</p></div></div></td></tr><tr><td><div><div><p><code>scopeValidationCriteria</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"AND"</p></div></div></td><td><div><div><p>The criteria to apply to the <code>scopes</code> values. Valid parameter values are "AND" or "OR".</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>enableProtectedResourceMetadata</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables <a href="https://www.rfc-editor.org/rfc/rfc9728">RFC 9728</a> OAuth 2.0 Protected Resource Metadata. When <code>true</code>, all <code>401</code> responses include a <code>WWW-Authenticate</code> header with the resource metadata URL <code>{api_path}/.well-known/oauth-protected-resource</code>.<br>When a client makes a GET request to this path, Omni Gateway responds with a JSON document containing the authorization server metadata. By default, Omni Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, <code><a href="https://auth.example.com/introspect">https://auth.example.com/introspect</a></code> becomes <code><a href="https://auth.example.com">https://auth.example.com</a></code>.</p></div></div></td></tr><tr><td><div><div><p><code>overrideProtectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.</p></div></div></td></tr><tr><td><div><div><p><code>protectedResourceMetadataAuthorizationServerUrl</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div></div></td><td><div><div><p>Server base URL to use when <code>overrideProtectedResourceMetadataAuthorizationServerUrl</code> is <code>true</code>.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: oauth2-token-introspection-flex
  config:
    introspectionURL: https://my-introspection.com/introspect
    authorizationValue: Basic am9obkBleGFtcGxlLmNvbTphYmMxMjM=
    validatedTokenTTL: 600
    authenticationTimeout: 10000
    skipClientIdValidation: false
    consumerBy: "client_id"
    exposeHeaders: true
    scopes: "profile email shopping"
    scopeValidationCriteria: "AND"
    maxCacheEntries: 1000
```

<!-- document id=d0736740f61356e1afefb6ab3b5d959c82920b4532505052eb55e0387d582f1e url=/mulesoft/current/en-us/gateway/1.13/agent-policies.md -->

---
product: Omni Gateway
version: 1.13
---

# Omni Gateway Agent Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Omni Gateway processes requests, enabling you to secure and govern your
server instances. Omni Gateway includes A2A and MCP specific policies that provide enhanced security
and control over agent interactions.

To apply a policy, see
[Applying Policies for Managed Omni Gateways and Connected Mode](https://docs.mulesoft.com/gateway/1.13/gateway-secure-conn).

Omni Gateway MCP and A2A server instances also support other Omni Gateway policies to protect server
instances through rate limiting, authentication, authorization, threat protection, monitoring, and
logging. For more information about MuleSoft-provided policies, see the
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements. For information about creating custom policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

## SSE Policies

Both A2A and MCP support the following policies for Server-Sent Events (SSE) streaming:

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-sse-logging">SSE Logging</a></p></td><td><p>Logs every SSE event while streaming</p></td></tr></tbody></table>

## A2A Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-agent-card">A2A Agent Card</a></p></td><td><p>Rewrites the Agent Card URL to match the server instance public URL</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-pii-detector">A2A PII Detector</a></p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-prompt-decorator">A2A Prompt Decorator</a></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-schema-validation">A2A Schema Validation</a></p></td><td><p>Validates agent requests to ensure they conform to the A2A specification</p></td></tr></tbody></table>

## A2A v1 Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-quality-evaluation">A2A Quality Evaluation</a></p></td><td><p>Evaluates completed A2A agent task responses using an LLM to score quality and completeness</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-agent-card">A2A v1 Agent Card</a></p></td><td><p>Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-azure-guardrails">A2A v1 Azure Content Guardrails</a></p></td><td><p>Evaluates A2A v1 agent messages against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-bedrock-guardrails">A2A v1 Bedrock Guardrails</a></p></td><td><p>Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-pii-detector">A2A v1 PII Detector</a></p></td><td><p>Detects personally identifiable information (PII) in A2A v1 requests across all transports</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-prompt-decorator">A2A v1 Prompt Decorator</a></p></td><td><p>Decorates A2A v1 prompts with additional context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-schema-validation">A2A v1 Schema Validation</a></p></td><td><p>Verifies that requests to the agent are compliant with the A2A v1.0 specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-a2a-v1-to-v03-transcoder">A2A v1 to v0.3 Transcoder</a></p></td><td><p>Transcodes protocol messages bidirectionally between A2A v1.0 JSON-RPC clients and A2A v0.3 backend servers</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-token-rate-limit">A2A v1 Token Based Rate Limit</a></p></td><td><p>Rate limits v1 A2A agent usage of upstream resources</p></td></tr></tbody></table>

## MCP Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-attribute-access-control">MCP Attribute-Based Access Control</a></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-global-access">MCP Global Access</a></p></td><td><p>Restricts which MCP tools are exposed by defining Allow and Block rules</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-pii-detector">MCP PII Detector</a></p></td><td><p>Detects personally identifiable information (PII) in Model Context Protocol (MCP) JSON-RPC traffic on both the request and response sides</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-payload-optimization">MCP Payload Optimization</a></p></td><td><p>Reduces tool response token consumption using one or more configurable methods: remove structural noise, trim oversized responses to match agent intent, or compress repeated structures into TOON</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-progressive-disclosure">MCP Tools Progressive Disclosure</a></p></td><td><p>Reduces context window token cost by exposing tools on-demand through search</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-schema-validation">MCP Schema Validation</a></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-support">MCP Support</a></p></td><td><p>Adds MCP support to an Omni Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-mcp-tool-mapping">MCP Tool Mapping</a></p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr></tbody></table>

## LLM Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-azure-content-safety">Azure Content Safety</a></p></td><td><p>Evaluates LLM prompts and responses against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-bedrock-guardrails">Amazon Bedrock Guardrails</a></p></td><td><p>Evaluates LLM prompts and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-llm-pii-detection">LLM PII Detection</a></p></td><td><p>Detects personally identifiable information (PII) in OpenAI and Anthropic format LLM requests and responses</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-llm-token-rate-limit">LLM Token Based Rate Limit</a></p></td><td><p>Limits Model Proxy usage based on the number of tokens consumed</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-llm-proxy-request-compression">Model Proxy Request Compression</a></p></td><td><p>Compresses message content and replayed tool results in Model Proxy request bodies before they reach the upstream provider, reducing billed tokens</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-regex-prompt-guard">Regex Prompt Guard</a></p></td><td><p>Blocks LLM requests that match deny-list regex patterns</p></td></tr></tbody></table>

## See Also

- [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder)

- [DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support)

<!-- document id=034de347b715edf84cfdf8cbe87d4efe4dcfcca0c9d320be2b3222beda92a8a8 url=/mulesoft/current/en-us/gateway/latest/agent-policies.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Omni Gateway Agent Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Omni Gateway processes requests, enabling you to secure and govern your
server instances. Omni Gateway includes A2A and MCP specific policies that provide enhanced security
and control over agent interactions.

To apply a policy, see
[Applying Policies for Managed Omni Gateways and Connected Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-conn).

Omni Gateway MCP and A2A server instances also support other Omni Gateway policies to protect server
instances through rate limiting, authentication, authorization, threat protection, monitoring, and
logging. For more information about MuleSoft-provided policies, see the
[Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements. For information about creating custom policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

## SSE Policies

Both A2A and MCP support the following policies for Server-Sent Events (SSE) streaming:

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-sse-logging">SSE Logging</a></p></td><td><p>Logs every SSE event while streaming</p></td></tr></tbody></table>

## A2A Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-agent-card">A2A Agent Card</a></p></td><td><p>Rewrites the Agent Card URL to match the server instance public URL</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-pii-detector">A2A PII Detector</a></p></td><td><p>Detects personally identifiable information (PII) in requests sent to the agent</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-prompt-decorator">A2A Prompt Decorator</a></p></td><td><p>Decorates prompts with context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-schema-validation">A2A Schema Validation</a></p></td><td><p>Validates agent requests to ensure they conform to the A2A specification</p></td></tr></tbody></table>

## A2A v1 Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-quality-evaluation">A2A Quality Evaluation</a></p></td><td><p>Evaluates completed A2A agent task responses using an LLM to score quality and completeness</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-agent-card">A2A v1 Agent Card</a></p></td><td><p>Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-azure-guardrails">A2A v1 Azure Content Guardrails</a></p></td><td><p>Evaluates A2A v1 agent messages against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-bedrock-guardrails">A2A v1 Bedrock Guardrails</a></p></td><td><p>Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-pii-detector">A2A v1 PII Detector</a></p></td><td><p>Detects personally identifiable information (PII) in A2A v1 requests across all transports</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-prompt-decorator">A2A v1 Prompt Decorator</a></p></td><td><p>Decorates A2A v1 prompts with additional context information</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-schema-validation">A2A v1 Schema Validation</a></p></td><td><p>Verifies that requests to the agent are compliant with the A2A v1.0 specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-a2a-v1-to-v03-transcoder">A2A v1 to v0.3 Transcoder</a></p></td><td><p>Transcodes protocol messages bidirectionally between A2A v1.0 JSON-RPC clients and A2A v0.3 backend servers</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-token-rate-limit">A2A v1 Token Based Rate Limit</a></p></td><td><p>Rate limits v1 A2A agent usage of upstream resources</p></td></tr></tbody></table>

## MCP Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control">MCP Attribute-Based Access Control</a></p></td><td><p>Controls access to tools, resources, and prompts based on user information such as Tiers, IP, Headers, or Claims</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access">MCP Global Access</a></p></td><td><p>Restricts which MCP tools are exposed by defining Allow and Block rules</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-pii-detector">MCP PII Detector</a></p></td><td><p>Blocks elicitation responses containing personally identifiable information (PII) from reaching MCP servers</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-payload-optimization">MCP Payload Optimization</a></p></td><td><p>Reduces tool response token consumption using one or more configurable methods: remove structural noise, trim oversized responses to match agent intent, or compress repeated structures into TOON</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-progressive-disclosure">MCP Tools Progressive Disclosure</a></p></td><td><p>Reduces context window token cost by exposing tools on-demand through search</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-schema-validation">MCP Schema Validation</a></p></td><td><p>Validates MCP requests to ensure they conform to the MCP specification</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support">MCP Support</a></p></td><td><p>Adds MCP support to an Omni Gateway MCP server instance. This policy is required for your MCP server instance to function properly.</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping">MCP Tool Mapping</a></p></td><td><p>Redefines tool names and descriptions to reduce prompt complexity and improve LLM comprehension</p></td></tr></tbody></table>

## LLM Policies

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-azure-content-safety">Azure Content Safety</a></p></td><td><p>Evaluates LLM prompts and responses against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-bedrock-guardrails">Amazon Bedrock Guardrails</a></p></td><td><p>Evaluates LLM prompts and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-crowdstrike-aidr-guardrails">CrowdStrike AIDR Guardrails</a></p></td><td><p>Evaluates OpenAI-format LLM prompts and responses against CrowdStrike Falcon AI Detection and Response (AIDR), rejecting or redacting flagged content</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-f5-guardrails">F5 Guardrails</a></p></td><td><p>Evaluates LLM prompts and responses against F5 AI Guardrails, blocking, flagging, or redacting flagged content</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-google-model-armor-guardrails">Google Model Armor Guardrails</a></p></td><td><p>Evaluates OpenAI and Gemini format LLM prompts and responses against a Google Cloud Model Armor template, blocking or redacting flagged content</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-llm-pii-detection">LLM PII Detection</a></p></td><td><p>Detects personally identifiable information (PII) in OpenAI and Anthropic format LLM requests and responses</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-llm-token-rate-limit">LLM Token Based Rate Limit</a></p></td><td><p>Limits Model Proxy usage based on the number of tokens consumed</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-llm-proxy-request-compression">Model Proxy Request Compression</a></p></td><td><p>Compresses message content and replayed tool results in Model Proxy request bodies before they reach the upstream provider, reducing billed tokens</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-regex-prompt-guard">Regex Prompt Guard</a></p></td><td><p>Blocks LLM requests that match deny-list regex patterns</p></td></tr></tbody></table>

## See Also

- [Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder)

- [DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support)

<!-- document id=e868a544adf1ad16848a823c6d1bec6af1098c190bab0304ae8fc4770c82bb4b url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-basic-deployments.md -->

---
product: Omni Gateway
version: 1.13
---

# Omni Gateway Deployment Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports multiple deployment models, which apply to both Connected Mode and Local Mode:

- [Standalone deployment](#standalone-deployment)

- [Ingress deployment](#ingress-deployment)

- [Egress deployment](#egress-deployment)

- [Sidecar deployment](#sidecar-deployment)

You can extend the deployment models in this overview to all technological stacks that have the
appropriate network controls applied. For more information about routing configuration modes, see
[Routing Configuration Methods](#routing-configuration-methods).

All the following diagrams show Omni Gateway running in Connected Mode. For Omni Gateway running in
Local Mode, the only difference is that Anypoint Platform would not be present in the deployment
model. This does not affect how information flows between Omni Gateway and the upstream and
downstream services.

## Standalone Deployment

In a standalone deployment, Omni Gateway acts as a standalone service that protects one or more
integration API flows by managing internal traffic.

As the following diagram shows, all traffic is inside an organization-owned network. The traffic
passes through Omni Gateway before reaching the consumer APIs.

![In a standalone deployment, Omni Gateway and the consumer applications are in the same network.](/mulesoft/current/en-us/gateway/1.13/_images/ad-standalone-deployment.png)

## Ingress Deployment

Similar to standalone deployment, in an ingress deployment, Omni Gateway acts as a standalone
service that protects one or more integration API flows. However, in an ingress deployment, Omni
Gateway manages external traffic entering the internal network. Ingress deployment is the most
common deployment model.

Omni Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all external traffic passes through Omni Gateway before reaching the
consumer APIs. Omni Gateway is typically deployed behind a load balancer, and the consumer
application does not belong to the same network as Omni Gateway or the APIs.

![In an ingress deployment, Omni Gateway and the consumer applications are in different networks.](/mulesoft/current/en-us/gateway/1.13/_images/ad-ingress-deployment.png)

> [!NOTE] Ingress deployment is not the same as a Kubernetes Ingress controller or Ingress
> `Resource`. For more information about routing configuration, see
> [Routing Configuration Methods](#routing-configuration-methods).

## Egress Deployment

An egress deployment is the opposite deployment model of an ingress deployment. Omni Gateway still
acts as a standalone service that protects one or more integration API flows. However, in an egress
deployment, Omni Gateway manages internal traffic exiting the internal network, for example, API
requests to non-organization-owned APIs.

Omni Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all internal traffic from the consumer application passes through
Omni Gateway before reaching the external APIs.

![A diagram of Anypoint Platform depicting the flow of data between the platform, an Omni Gateway, APIs, and a user](/mulesoft/current/en-us/gateway/1.13/_images/ad-egress-deployment.png)

## Sidecar Deployment

In a sidecar deployment, each Omni Gateway deployment only protects the APIs exposed by its
protected service. A new Omni Gateway replica is added with each new protected service.

As the following diagram shows, traffic in a sidecar deployment passes through Omni Gateway to the
respective consumer API. The consumer application can belong to the same network as Omni Gateway or
an external network.

![In a sidecar deployment, Omni Gateway and the consumer application are in the same Kubernetes pod.](/mulesoft/current/en-us/gateway/1.13/_images/ad-sidecar-deployment.png)

## Routing Configuration Methods

There are different routing configuration methods dependent on what mode Omni Gateway is running in
or what technological stack Omni Gateway is deployed on.

How connections between Omni Gateway and services are configured is independent of the deployment
model.

### Control Plane

In control plane routing configuration, Omni Gateway and service connections are configured in a
remote control plane. For Omni Gateway, the control plane is Anypoint Platfrom. Control plane
configuration is only available in Omni Gateway Connected Mode.

### Custom Resource Definitions (CRDs)

In custom resource definitions (CRDs) routing configuration, Omni Gateway and service connections
are configured in custom resource yaml files.

For Omni Gateway, the CRDs are `APIinstance`, `Service`, `PolicyBinding`, and `Configuration` and
are defined in the [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

In Omni Gateway CRDs define connections in Local Mode but are also necessary for some connections in
Connected Mode.

### Kubernetes Ingress Resource

Omni Gateways running in Local Mode and deployed on Kubernetes can use Kubernetes `Ingress`
resources to define connection routing. When routing is defined via `Ingress` resources, Omni
Gateway acts as an Ingress Controller. `Ingress` resources are only avaliable in Kubernetes Local
Mode.

You can use `Ingress` resources and CRDs simultaneously.

For more information about how to configure Omni Gateway as an Ingress Controller, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class).

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc-overview)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-shared-storage)

<!-- document id=c4b9245284d2092c6ea66b5e2e8e32b6156ec880ff83fe98669931db58a15580 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-basic-deployments.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Omni Gateway Deployment Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports multiple deployment models, which apply to both Connected Mode and Local Mode:

- [Standalone deployment](#standalone-deployment)

- [Ingress deployment](#ingress-deployment)

- [Egress deployment](#egress-deployment)

- [Sidecar deployment](#sidecar-deployment)

You can extend the deployment models in this overview to all technological stacks that have the
appropriate network controls applied. For more information about routing configuration modes, see
[Routing Configuration Methods](#routing-configuration-methods).

All the following diagrams show Omni Gateway running in Connected Mode. For Omni Gateway running in
Local Mode, the only difference is that Anypoint Platform would not be present in the deployment
model. This does not affect how information flows between Omni Gateway and the upstream and
downstream services.

## Standalone Deployment

In a standalone deployment, Omni Gateway acts as a standalone service that protects one or more
integration API flows by managing internal traffic.

As the following diagram shows, all traffic is inside an organization-owned network. The traffic
passes through Omni Gateway before reaching the consumer APIs.

![In a standalone deployment, Omni Gateway and the consumer applications are in the same network.](/mulesoft/current/en-us/gateway/latest/_images/ad-standalone-deployment.png)

## Ingress Deployment

Similar to standalone deployment, in an ingress deployment, Omni Gateway acts as a standalone
service that protects one or more integration API flows. However, in an ingress deployment, Omni
Gateway manages external traffic entering the internal network. Ingress deployment is the most
common deployment model.

Omni Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all external traffic passes through Omni Gateway before reaching the
consumer APIs. Omni Gateway is typically deployed behind a load balancer, and the consumer
application does not belong to the same network as Omni Gateway or the APIs.

![In an ingress deployment, Omni Gateway and the consumer applications are in different networks.](/mulesoft/current/en-us/gateway/latest/_images/ad-ingress-deployment.png)

> [!NOTE] Ingress deployment is not the same as a Kubernetes Ingress controller or Ingress
> `Resource`. For more information about routing configuration, see
> [Routing Configuration Methods](#routing-configuration-methods).

## Egress Deployment

An egress deployment is the opposite deployment model of an ingress deployment. Omni Gateway still
acts as a standalone service that protects one or more integration API flows. However, in an egress
deployment, Omni Gateway manages internal traffic exiting the internal network, for example, API
requests to non-organization-owned APIs.

Omni Gateway can act as both an ingress and an egress gateway.

As the following diagram shows, all internal traffic from the consumer application passes through
Omni Gateway before reaching the external APIs.

![A diagram of Anypoint Platform depicting the flow of data between the platform, an Omni Gateway, APIs, and a user](/mulesoft/current/en-us/gateway/latest/_images/ad-egress-deployment.png)

## Sidecar Deployment

In a sidecar deployment, each Omni Gateway deployment only protects the APIs exposed by its
protected service. A new Omni Gateway replica is added with each new protected service.

As the following diagram shows, traffic in a sidecar deployment passes through Omni Gateway to the
respective consumer API. The consumer application can belong to the same network as Omni Gateway or
an external network.

![In a sidecar deployment, Omni Gateway and the consumer application are in the same Kubernetes pod.](/mulesoft/current/en-us/gateway/latest/_images/ad-sidecar-deployment.png)

## Routing Configuration Methods

There are different routing configuration methods dependent on what mode Omni Gateway is running in
or what technological stack Omni Gateway is deployed on.

How connections between Omni Gateway and services are configured is independent of the deployment
model.

### Control Plane

In control plane routing configuration, Omni Gateway and service connections are configured in a
remote control plane. For Omni Gateway, the control plane is Anypoint Platfrom. Control plane
configuration is only available in Omni Gateway Connected Mode.

### Custom Resource Definitions (CRDs)

In custom resource definitions (CRDs) routing configuration, Omni Gateway and service connections
are configured in custom resource yaml files.

For Omni Gateway, the CRDs are `APIinstance`, `Service`, `PolicyBinding`, and `Configuration` and
are defined in the [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

In Omni Gateway CRDs define connections in Local Mode but are also necessary for some connections in
Connected Mode.

### Kubernetes Ingress Resource

Omni Gateways running in Local Mode and deployed on Kubernetes can use Kubernetes `Ingress`
resources to define connection routing. When routing is defined via `Ingress` resources, Omni
Gateway acts as an Ingress Controller. `Ingress` resources are only avaliable in Kubernetes Local
Mode.

You can use `Ingress` resources and CRDs simultaneously.

For more information about how to configure Omni Gateway as an Ingress Controller, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class).

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc-overview)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-shared-storage)

<!-- document id=455d61b20c84fd7df0ad7688fc99e5afed27bd087e23da8373be0243666e9949 url=/mulesoft/current/en-us/gateway/1.13/index.md -->

---
product: Omni Gateway
version: 1.13
---

# Omni Gateway Overview

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway (formerly Flex Gateway) is an Envoy-based, ultrafast lightweight API gateway designed
to manage and secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD
workflows, Omni Gateway delivers the performance required for the most demanding applications and
microservices while providing enterprise security and manageability across any environment.

The following video provides a quick overview of Omni Gateway:

![](https://play.vidyard.com/3LncCho6hfvbLMKbg1AM28.jpg)

## Omni Gateway Architecture

Omni Gateway comprises two components that work in tandem:

- [Control plane](#control_plane)

- [Runtime](#runtime)

The following graphic diagrams the relationship between these components:

![A flowchart that illustrates the deployment and management of APIs](/mulesoft/current/en-us/gateway/1.13/_images/gateway-concepts-control-plane-diagram.png)

### Control plane

The control plane is a MuleSoft-hosted platform that centralizes management and observability,
enabling you to:

- Build APIs.

- Add policies.

- Deploy APIs into the runtime.

- Monitor APIs in Anypoint API Manager.

- Configure the runtime in Anypoint Runtime Manager.

### Runtime

The gateway runtime receives commands from the control plane and routes and protects the backend
APIs. Built with security in mind, Omni Gateway secures communications between the runtime and the
control plane through mTLS and HTTPs.

## Scaling

A single Omni Gateway can support up to 1,000 backend APIs. For high availability, it is best to
deploy multiple gateways running in parallel. Deploying multiple gateways increases gateway
performance and robustness, and is recommended for high-performance applications that must scale.

## Supported Protocols

Omni Gateway supports the following protocols:

- HTTP

- WebSocket

- SOAP

- gRPC

- GraphQL

- OAS3 REST API instances

- Model Context Protocol (MCP)

- Agent2Agent (A2A)

> [!NOTE] WebSocket API instances don’t support SLA tiers.

## Deployment Types

You can deploy Omni Gateway as a Managed or Self-Managed Omni Gateway. Managed Omni Gateway provides
a fully managed option on CloudHub 2.0 or Runtime Fabric, and Self-Managed Omni Gateway provides
more options and control.

- [Managed Omni Gateway](#managed)

- [Self-Managed Omni Gateway](#self_managed)

### Managed Omni Gateway

Managed Omni Gateway is a fully hosted version of Omni Gateway on CloudHub 2.0 or Runtime Fabric,
hosted and managed on the Anypoint Platform by MuleSoft. Managed Omni Gateway provides high
availability, autoscaling, less operational overhead, and regular automatic patches and upgrades. It
is designed to simplify API gateway operation through point-and-click setup, and monitoring, and
MuleSoft handles the maintenance and infrastructure.

In Managed Omni Gateway, each runtime unit is called a gateway instance.

### Self-Managed Omni Gateway

Self-Managed Omni Gateway is a distributed runtime entity that you can install in any cloud data
center or, for testing purposes, on your local laptop. Self-Managed Omni Gateway requires you to
manage the underlying infrastructure. Various installation options are available for the
Self-Managed Omni Gateway, including Docker containers, as a sidecar to a backend application in a
Docker container, as a Kubernetes Deployment, or on various Linux environments.

In Self-Managed Omni Gateway, each runtime unit is called a replica. For high availability, it is
best to deploy Self-Managed Omni Gateway as a cluster with multiple replicas running in parallel.
Using clusters increases gateway performance and robustness, and is recommended for high-performance
applications that must scale.

Self-Managed Omni Gateway includes a Fluent Bit implementation, which enables log output to local
files, or to aggregators such as New Relic, Sumo Logic, and Splunk. You can also configure external
REDIS storage for use with distributed rate limiting and caching. Gateway replicas utilize this
storage as a temporary workspace for rate limit coordination, which is pivotal in preserving
customer service level agreements.

Self-Managed Omni Gateway can be installed in either of these two modes:

- [Self-Managed Omni Gateway in Connected Mode](#connected_mode)

- [Self-Managed Omni Gateway in Local Mode](#local_mode)

### Self-Managed Omni Gateway in Connected Mode

In Connected Mode, the gateway is fully connected to the MuleSoft control plane. This connection
allows for centralized management, observability, and security. Anypoint API Manager enables full
API lifecycle management and policy configuration. Anypoint Runtime Manager enables you to deploy
and configure your gateway.

Choose Connected Mode for a UI-based experience to deploy policies, and for managing and monitoring
the gateway.

### Self-Managed Omni Gateway in Local Mode

You can also configure and manage a standalone gateway that is mostly disconnected from the control
plane. Choose Local Mode for this experience.

> [!NOTE] Omni Gateway deployed in Local Mode only connects to the control plane for registration
> and logging usage metrics.

In Local Mode, you manage all configuration and policy applications with locally stored declarative
configuration files.

Use Local Mode to build CI/CD pipelines for application deployments.

### Summary of Differences

The following table summarizes the differences between Connected Mode and Local Mode.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th></th><th>Connected Mode</th><th>Local Mode</th></tr></thead><tbody><tr><td><div><div><p><strong>Use Case</strong></p></div></div></td><td><div><div><p>Centralize management, observability, and security. Omni Gateway connects to the control plane.</p></div></div></td><td><div><div><p>Operate independently of the control plane in a mostly disconnected manner. Manage with locally stored declarative configuration files. Build CI/CD pipelines.</p></div></div></td></tr><tr><td><div><div><p><strong>Policy Application</strong></p></div></div></td><td><div><div><p>Via API Manager</p></div></div></td><td><div><div><p>Via local declarative configuration files</p></div></div></td></tr><tr><td><div><div><p><strong>Air-Gapped?</strong></p></div></div></td><td><div><div><p>No. Omni Gateway is connected to the control plane.</p></div></div></td><td><div><div><p>No. Omni Gateway is managed locally but only connected to the control plane for registration and usage metrics.</p></div></div></td></tr></tbody></table>

## Deployment and Installation Options

### Managed Deployment Options

You can deploy Managed Omni Gateway on CloudHub 2.0 and Runtime Fabric using Runtime Manager. For
details see [Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-managed-set-up).

### Self-Managed Installation Options

You can install Self-Managed Omni Gateway in a variety of ways:

- A standalone runtime in a Docker container deployed on Heroku from Salesforce

  To learn more, see
  [Mastering API Integration: Salesforce, Heroku, and MuleSoft Omni Gateway](https://blog.heroku.com/mastering-api-integration-salesforce-heroku-mulesoft-anypoint-flex-gateway).

- A standalone runtime in a Docker container

- A sidecar to a backend application in a Docker container, thereby protecting a single backend
  application

- A Kubernetes `Deployment` for high-availability, high-performance use cases

- An OpenShift on IBM Power `Deployment` for high-availability, high-performance use cases

- A standalone single runtime or replica on various Linux environments, including:

  - Amazon Linux 2023

  - CentOS 8

  - Debian Bookworm

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - Ubuntu Jammy

A standalone gateway is good for protecting a limited number of APIs with low transaction volume.
However, for other scenarios, or if high availability and reliability are critical, consider using
an Ingress controller in Kubernetes.

## Version Retirement Dates

For information about Omni Gateway version retirement dates, refer to
[MuleSoft Product Versioning and Back Support Policy](https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Shared Responsibility

The successful operation of Omni Gateway is a responsibility shared between you and MuleSoft.

### MuleSoft Responsibility

MuleSoft is responsible for:

- Providing and supporting Omni Gateway (including the agent, Envoy package, and Fluent Bit package)

- Providing and supporting a base Helm chart for the installation of Omni Gateway in a Kubernetes
  cluster

- Providing and supporting an online Docker image registry

- Providing and supporting an online package repository for installation on Linux

### Your Responsibility

When running on any target, you are responsible for:

- Maintaining connectivity to the Anypoint Control Plane

- Not running third-party software that interferes with normal Omni Gateway operation, such as
  antivirus, DPI, or application security systems

When running in Kubernetes, you are responsible for:

- Adapting the base Helm chart for your specific needs

- Managing the Kubernetes `Deployment`, including:

  - External load balancing

  - Customizations to `Ingress` resources

  - Log forwarding

  - Monitoring

  - Network ports, NAT gateways, and proxies

  - Container runtime and networking

  - Provisioning and management of the Kubernetes environment, which requires:

    - Your IT team to provision and manage the infrastructure

    - Your network team to configure allowed ports and proxy settings

    - Your security team to verify compliance and obtain security certificates

See [Viewing Usage Reports](https://docs.mulesoft.com/general/usage-reports) for information about your monthly Omni
Gateway usage.

## Next Steps

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

<!-- document id=f792d4243345fe752166c9d7970237076c47031512ea5cfae4b9a91a2eb2151e url=/mulesoft/current/en-us/gateway/latest/index.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Omni Gateway Overview

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway (formerly Flex Gateway) is an Envoy-based, ultrafast lightweight API gateway designed
to manage and secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD
workflows, Omni Gateway delivers the performance required for the most demanding applications and
microservices while providing enterprise security and manageability across any environment.

The following video provides a quick overview of Omni Gateway:

![](https://play.vidyard.com/3LncCho6hfvbLMKbg1AM28.jpg)

## Omni Gateway Architecture

Omni Gateway comprises two components that work in tandem:

- [Control plane](#control_plane)

- [Runtime](#runtime)

The following graphic diagrams the relationship between these components:

![A flowchart that illustrates the deployment and management of APIs](/mulesoft/current/en-us/gateway/latest/_images/gateway-concepts-control-plane-diagram.png)

### Control plane

The control plane is a MuleSoft-hosted platform that centralizes management and observability,
enabling you to:

- Build APIs.

- Add policies.

- Deploy APIs into the runtime.

- Monitor APIs in Anypoint API Manager.

- Configure the runtime in Anypoint Runtime Manager.

### Runtime

The gateway runtime receives commands from the control plane and routes and protects the backend
APIs. Built with security in mind, Omni Gateway secures communications between the runtime and the
control plane through mTLS and HTTPs.

## Scaling

A single Omni Gateway can support up to 1,000 backend APIs. For high availability, it is best to
deploy multiple gateways running in parallel. Deploying multiple gateways increases gateway
performance and robustness, and is recommended for high-performance applications that must scale.

## Supported Protocols

Omni Gateway supports the following protocols:

- HTTP

- WebSocket

- SOAP

- gRPC

- GraphQL

- OAS3 REST API instances

- Model Context Protocol (MCP)

- Agent2Agent (A2A)

> [!NOTE] WebSocket API instances don’t support SLA tiers.

## Deployment Types

You can deploy Omni Gateway as a Managed or Self-Managed Omni Gateway. Managed Omni Gateway provides
a fully managed option on CloudHub 2.0 or Runtime Fabric, and Self-Managed Omni Gateway provides
more options and control.

- [Managed Omni Gateway](#managed)

- [Self-Managed Omni Gateway](#self_managed)

### Managed Omni Gateway

Managed Omni Gateway is a fully hosted version of Omni Gateway on CloudHub 2.0 or Runtime Fabric,
hosted and managed on the Anypoint Platform by MuleSoft. Managed Omni Gateway provides high
availability, autoscaling, less operational overhead, and regular automatic patches and upgrades. It
is designed to simplify API gateway operation through point-and-click setup, and monitoring, and
MuleSoft handles the maintenance and infrastructure.

In Managed Omni Gateway, each runtime unit is called a gateway instance.

### Self-Managed Omni Gateway

Self-Managed Omni Gateway is a distributed runtime entity that you can install in any cloud data
center or, for testing purposes, on your local laptop. Self-Managed Omni Gateway requires you to
manage the underlying infrastructure. Various installation options are available for the
Self-Managed Omni Gateway, including Docker containers, as a sidecar to a backend application in a
Docker container, as a Kubernetes Deployment, or on various Linux environments.

In Self-Managed Omni Gateway, each runtime unit is called a replica. For high availability, it is
best to deploy Self-Managed Omni Gateway as a cluster with multiple replicas running in parallel.
Using clusters increases gateway performance and robustness, and is recommended for high-performance
applications that must scale.

Self-Managed Omni Gateway includes a Fluent Bit implementation, which enables log output to local
files, or to aggregators such as New Relic, Sumo Logic, and Splunk. You can also configure external
REDIS storage for use with distributed rate limiting and caching. Gateway replicas utilize this
storage as a temporary workspace for rate limit coordination, which is pivotal in preserving
customer service level agreements.

Self-Managed Omni Gateway can be installed in either of these two modes:

- [Self-Managed Omni Gateway in Connected Mode](#connected_mode)

- [Self-Managed Omni Gateway in Local Mode](#local_mode)

### Self-Managed Omni Gateway in Connected Mode

In Connected Mode, the gateway is fully connected to the MuleSoft control plane. This connection
allows for centralized management, observability, and security. Anypoint API Manager enables full
API lifecycle management and policy configuration. Anypoint Runtime Manager enables you to deploy
and configure your gateway.

Choose Connected Mode for a UI-based experience to deploy policies, and for managing and monitoring
the gateway.

### Self-Managed Omni Gateway in Local Mode

You can also configure and manage a standalone gateway that is mostly disconnected from the control
plane. Choose Local Mode for this experience.

> [!NOTE] Omni Gateway deployed in Local Mode only connects to the control plane for registration
> and logging usage metrics.

In Local Mode, you manage all configuration and policy applications with locally stored declarative
configuration files.

Use Local Mode to build CI/CD pipelines for application deployments.

### Summary of Differences

The following table summarizes the differences between Connected Mode and Local Mode.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th></th><th>Connected Mode</th><th>Local Mode</th></tr></thead><tbody><tr><td><div><div><p><strong>Use Case</strong></p></div></div></td><td><div><div><p>Centralize management, observability, and security. Omni Gateway connects to the control plane.</p></div></div></td><td><div><div><p>Operate independently of the control plane in a mostly disconnected manner. Manage with locally stored declarative configuration files. Build CI/CD pipelines.</p></div></div></td></tr><tr><td><div><div><p><strong>Policy Application</strong></p></div></div></td><td><div><div><p>Via API Manager</p></div></div></td><td><div><div><p>Via local declarative configuration files</p></div></div></td></tr><tr><td><div><div><p><strong>Air-Gapped?</strong></p></div></div></td><td><div><div><p>No. Omni Gateway is connected to the control plane.</p></div></div></td><td><div><div><p>No. Omni Gateway is managed locally but only connected to the control plane for registration and usage metrics.</p></div></div></td></tr></tbody></table>

## Deployment and Installation Options

### Managed Deployment Options

You can deploy Managed Omni Gateway on CloudHub 2.0 and Runtime Fabric using Runtime Manager. For
details see [Deploy a Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up).

### Self-Managed Installation Options

You can install Self-Managed Omni Gateway in a variety of ways:

- A standalone runtime in a Docker container deployed on Heroku from Salesforce

  To learn more, see
  [Mastering API Integration: Salesforce, Heroku, and MuleSoft Omni Gateway](https://blog.heroku.com/mastering-api-integration-salesforce-heroku-mulesoft-anypoint-flex-gateway).

- A standalone runtime in a Docker container

- A sidecar to a backend application in a Docker container, thereby protecting a single backend
  application

- A Kubernetes `Deployment` for high-availability, high-performance use cases

- An OpenShift on IBM Power `Deployment` for high-availability, high-performance use cases

- A standalone single runtime or replica on various Linux environments, including:

  - Amazon Linux 2023

  - CentOS 8

  - Debian Bookworm

  - Red Hat Enterprise Linux (9)

  - Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

  - Ubuntu Jammy

A standalone gateway is good for protecting a limited number of APIs with low transaction volume.
However, for other scenarios, or if high availability and reliability are critical, consider using
an Ingress controller in Kubernetes.

## Version Retirement Dates

For information about Omni Gateway version retirement dates, refer to
[MuleSoft Product Versioning and Back Support Policy](https://www.salesforce.com/en-us/wp-content/uploads/sites/4/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Shared Responsibility

The successful operation of Omni Gateway is a responsibility shared between you and MuleSoft.

### MuleSoft Responsibility

MuleSoft is responsible for:

- Providing and supporting Omni Gateway (including the agent, Envoy package, and Fluent Bit package)

- Providing and supporting a base Helm chart for the installation of Omni Gateway in a Kubernetes
  cluster

- Providing and supporting an online Docker image registry

- Providing and supporting an online package repository for installation on Linux

### Your Responsibility

When running on any target, you are responsible for:

- Maintaining connectivity to the Anypoint Control Plane

- Not running third-party software that interferes with normal Omni Gateway operation, such as
  antivirus, DPI, or application security systems

When running in Kubernetes, you are responsible for:

- Adapting the base Helm chart for your specific needs

- Managing the Kubernetes `Deployment`, including:

  - External load balancing

  - Customizations to `Ingress` resources

  - Log forwarding

  - Monitoring

  - Network ports, NAT gateways, and proxies

  - Container runtime and networking

  - Provisioning and management of the Kubernetes environment, which requires:

    - Your IT team to provision and manage the infrastructure

    - Your network team to configure allowed ports and proxy settings

    - Your security team to verify compliance and obtain security certificates

See [Viewing Usage Reports](https://docs.mulesoft.com/general/usage-reports) for information about your monthly Omni
Gateway usage.

## Next Steps

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

<!-- document id=49f2be42ce628fb2824bdb04ea0f630b23ed94978ea62f856a78b6eb5967fc14 url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-overview.md -->

---
product: Omni Gateway
version: 1.13
---

# Omni Gateway Reference Architecture

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following architecture diagrams explain Omni Gateway concepts and deployments:

- [Omni Gateway Deployment Models](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-basic-deployments)

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc-overview)

  - [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1)

  - [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2)

  - [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3)

  - [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4)

- [High Availability and Disaster Recovery](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-dr-ha-overview)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-shared-storage)

<!-- document id=a9ab8f5b18270aaaee4ad231ecaf5fb3320171812e946b5221f0b4d04a017174 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-overview.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Omni Gateway Reference Architecture

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following architecture diagrams explain Omni Gateway concepts and deployments:

- [Omni Gateway Deployment Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-basic-deployments)

- [Integration Use Cases](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc-overview)

  - [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1)

  - [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2)

  - [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3)

  - [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4)

- [High Availability and Disaster Recovery](https://docs.mulesoft.com/gateway/latest/gateway-architecture-dr-ha-overview)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-shared-storage)

<!-- document id=5a2c1d88cffca6ca22c125273f21e229be81acf3649925c194bc3735aa99a0b7 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-release-notes.md -->

---
product: Omni Gateway
version: 1.12
---

# Omni Gateway Release Notes

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Mulesoft Omni Gateway is an Envoy-based, ultrafast lightweight API gateway designed to manage and
secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD workflows, Omni
Gateway delivers the performance required for the most demanding applications and microservices
while providing enterprise security and manageability across any environment.

The following release notes are provided for Omni Gateway:

- [Omni Gateway Release Notes](https://docs.mulesoft.com/release-notes/gateway/gateway-release-notes)

- [Model Proxy Release Notes](https://docs.mulesoft.com/release-notes/gateway/model-proxy-release-notes)

## Policy Release Notes

The following release notes are provided for Omni Gateway Policies:

<table><colgroup><col> <col></colgroup><thead><tr><th>Category</th><th>Policy</th></tr></thead><tbody><tr><td rowspan="16"><p><strong>A2A</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-agent-card-release-notes">A2A Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-intask-authorization-code-policy-release-notes">A2A In-Task Authorization Code</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/credential-injection-oauth2-obo-release-notes">A2A OAuth2 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-pii-detector-release-notes">A2A PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-prompt-decorator-release-notes">A2A Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-quality-evaluation-release-notes">A2A Quality Evaluation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-schema-validation-release-notes">A2A Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-token-rate-limit-release-notes">A2A Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-agent-card-release-notes">A2A v1 Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-azure-guardrails-release-notes">A2A v1 Azure Content Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-bedrock-guardrails-release-notes">A2A v1 Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-pii-detector-release-notes">A2A v1 PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-prompt-decorator-release-notes">A2A v1 Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-schema-validation-release-notes">A2A v1 Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-to-v03-transcoder-release-notes">A2A v1 to v0.3 Transcoder</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-token-rate-limit-release-notes">A2A v1 Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>A2A and MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/agent-connection-telemetry-release-notes">Agent Connection Telemetry</a></p></td></tr><tr><td rowspan="2"><p><strong>Compliance</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/client-id-enforcement-release-notes">Client ID Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/cors-release-notes">Cross-Origin Resource Sharing (CORS)</a></p></td></tr><tr><td rowspan="5"><p><strong>GraphQL</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-access-control-release-notes">GraphQL Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-introspection-control-release-notes">GraphQL Introspection Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-operation-limits-release-notes">GraphQL Operation Limits</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-schema-validation-release-notes">GraphQL Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-static-query-complexity-release-notes">GraphQL Static Query Complexity</a></p></td></tr><tr><td rowspan="9"><p><strong>LLM</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/bedrock-guardrails-release-notes">Amazon Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/azure-content-safety-release-notes">Azure Content Safety</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/crowdstrike-aidr-guardrails-release-notes">CrowdStrike AIDR Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/f5-guardrails-release-notes">F5 Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/google-model-armor-guardrails-release-notes">Google Model Armor Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-pii-detection-release-notes">LLM PII Detection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-token-rate-limit-release-notes">LLM Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-proxy-request-compression-release-notes">Model Proxy Request Compression</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/regex-prompt-guard-policy-release-notes">Regex Prompt Guard</a></p></td></tr><tr><td rowspan="8"><p><strong>MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-attribute-access-control-release-notes">MCP Attribute-Based Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-global-access-release-notes">MCP Global Access</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-pii-detector-release-notes">MCP PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-payload-optimization-release-notes">MCP Payload Optimization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-progressive-disclosure-release-notes">MCP Tools Progressive Disclosure</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-schema-validation-release-notes">MCP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-support-release-notes">MCP Support</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-tool-mapping-release-notes">MCP Tool Mapping</a></p></td></tr><tr><td rowspan="12"><p><strong>Quality of Service</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-circuit-breaker-release-notes">Circuit Breaker</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/health-check-release-notes">Health Check</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/http-caching-release-notes">HTTP Caching</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-release-notes">Rate Limiting</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-sla-release-notes">Rate Limiting: SLA-based</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/response-timeout-release-notes">Response Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/spike-control-release-notes">Spike Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/stream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-route-release-notes">Traffic Management for Multiple Upstream Services</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-release-notes">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-upstream-idle-timeout-release-notes">Upstream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/websocket-connection-limit-release-notes">WebSocket Connection Limit</a></p></td></tr><tr><td><p><strong>SSE</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/sse-logging-release-notes">SSE Logging</a></p></td></tr><tr><td rowspan="24"><p><strong>Security</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/api-security-identification-header-release-notes">API Security-Identification Header</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-signature-release-notes">AWS Request Signature</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-ldap-release-notes">Basic Authentication: LDAP</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-simple-release-notes">Basic Authentication: Simple</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-api-key-release-notes">Credential Injection API Key</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-basic-auth-release-notes">Credential Injection Basic Authentication</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-jwt-generation-release-notes">Credential Injection JWT Generation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-release-notes">Credential Injection OAuth 2.0</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-authorization-release-notes">External Authorization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/injection-protection-release-notes">Injection Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-allowlist-release-notes">IP Allowlist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-blocklist-release-notes">IP Blocklist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/json-threat-protection-release-notes">JSON Threat Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/jwt-validation-release-notes">JWT Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-obo-release-notes">OAuth 2.0 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-protected-resource-metadata-release-notes">OAuth 2.0 Protected Resource Metadata</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-token-introspection-release-notes">OAuth 2.0 Token Introspection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/openid-token-enforcement-release-notes">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/schema-validation-release-notes">Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/soap-schema-validation-release-notes">SOAP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-release-notes">Transport Layer Security (TLS) - Inbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-outbound-release-notes">Transport Layer Security (TLS) - Outbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/web-services-security-release-notes">WS-Security</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/xml-threat-protection-release-notes">XML Threat Protection</a></p></td></tr><tr><td rowspan="8"><p><strong>Transformation</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-lambda-release-notes">AWS Lambda</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-body-transformation-release-notes">DataWeave Body Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-headers-transformation-release-notes">DataWeave Headers Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-request-filter-release-notes">DataWeave Request Filter</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-processing-release-notes">External Processing</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-injection-release-notes">Header Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-removal-release-notes">Header Removal</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/javascript-scripting-release-notes">JavaScript Scripting</a></p></td></tr><tr><td rowspan="3"><p><strong>Troubleshooting</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/message-logging-release-notes">Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-message-logging-release-notes">Outbound Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tracing-release-notes">Tracing</a></p></td></tr></tbody></table>

## See Also

- [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.12/flex-gateway-version-lifecycle)

- [Edge and LTS Releases for Omni Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-version-lifecycle#edge-lts)

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=281e6590b014e04c686864b4acebad57899062e255fae577915a23db2343655f url=/mulesoft/current/en-us/gateway/1.13/gateway-release-notes.md -->

---
product: Omni Gateway
version: 1.13
---

# Omni Gateway Release Notes

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Mulesoft Omni Gateway is an Envoy-based, ultrafast lightweight API gateway designed to manage and
secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD workflows, Omni
Gateway delivers the performance required for the most demanding applications and microservices
while providing enterprise security and manageability across any environment.

The following release notes are provided for Omni Gateway:

- [Omni Gateway Release Notes](https://docs.mulesoft.com/release-notes/gateway/gateway-release-notes)

- [Model Proxy Release Notes](https://docs.mulesoft.com/release-notes/gateway/model-proxy-release-notes)

## Policy Release Notes

The following release notes are provided for Omni Gateway Policies:

<table><colgroup><col> <col></colgroup><thead><tr><th>Category</th><th>Policy</th></tr></thead><tbody><tr><td rowspan="16"><p><strong>A2A</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-agent-card-release-notes">A2A Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-intask-authorization-code-policy-release-notes">A2A In-Task Authorization Code</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/credential-injection-oauth2-obo-release-notes">A2A OAuth2 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-pii-detector-release-notes">A2A PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-prompt-decorator-release-notes">A2A Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-quality-evaluation-release-notes">A2A Quality Evaluation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-schema-validation-release-notes">A2A Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-token-rate-limit-release-notes">A2A Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-agent-card-release-notes">A2A v1 Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-azure-guardrails-release-notes">A2A v1 Azure Content Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-bedrock-guardrails-release-notes">A2A v1 Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-pii-detector-release-notes">A2A v1 PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-prompt-decorator-release-notes">A2A v1 Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-schema-validation-release-notes">A2A v1 Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-to-v03-transcoder-release-notes">A2A v1 to v0.3 Transcoder</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-token-rate-limit-release-notes">A2A v1 Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>A2A and MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/agent-connection-telemetry-release-notes">Agent Connection Telemetry</a></p></td></tr><tr><td rowspan="2"><p><strong>Compliance</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/client-id-enforcement-release-notes">Client ID Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/cors-release-notes">Cross-Origin Resource Sharing (CORS)</a></p></td></tr><tr><td rowspan="5"><p><strong>GraphQL</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-access-control-release-notes">GraphQL Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-introspection-control-release-notes">GraphQL Introspection Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-operation-limits-release-notes">GraphQL Operation Limits</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-schema-validation-release-notes">GraphQL Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-static-query-complexity-release-notes">GraphQL Static Query Complexity</a></p></td></tr><tr><td rowspan="9"><p><strong>LLM</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/bedrock-guardrails-release-notes">Amazon Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/azure-content-safety-release-notes">Azure Content Safety</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/crowdstrike-aidr-guardrails-release-notes">CrowdStrike AIDR Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/f5-guardrails-release-notes">F5 Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/google-model-armor-guardrails-release-notes">Google Model Armor Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-pii-detection-release-notes">LLM PII Detection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-token-rate-limit-release-notes">LLM Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-proxy-request-compression-release-notes">Model Proxy Request Compression</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/regex-prompt-guard-policy-release-notes">Regex Prompt Guard</a></p></td></tr><tr><td rowspan="8"><p><strong>MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-attribute-access-control-release-notes">MCP Attribute-Based Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-global-access-release-notes">MCP Global Access</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-pii-detector-release-notes">MCP PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-payload-optimization-release-notes">MCP Payload Optimization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-progressive-disclosure-release-notes">MCP Tools Progressive Disclosure</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-schema-validation-release-notes">MCP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-support-release-notes">MCP Support</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-tool-mapping-release-notes">MCP Tool Mapping</a></p></td></tr><tr><td rowspan="12"><p><strong>Quality of Service</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-circuit-breaker-release-notes">Circuit Breaker</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/health-check-release-notes">Health Check</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/http-caching-release-notes">HTTP Caching</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-release-notes">Rate Limiting</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-sla-release-notes">Rate Limiting: SLA-based</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/response-timeout-release-notes">Response Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/spike-control-release-notes">Spike Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/stream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-route-release-notes">Traffic Management for Multiple Upstream Services</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-release-notes">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-upstream-idle-timeout-release-notes">Upstream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/websocket-connection-limit-release-notes">WebSocket Connection Limit</a></p></td></tr><tr><td><p><strong>SSE</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/sse-logging-release-notes">SSE Logging</a></p></td></tr><tr><td rowspan="24"><p><strong>Security</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/api-security-identification-header-release-notes">API Security-Identification Header</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-signature-release-notes">AWS Request Signature</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-ldap-release-notes">Basic Authentication: LDAP</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-simple-release-notes">Basic Authentication: Simple</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-api-key-release-notes">Credential Injection API Key</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-basic-auth-release-notes">Credential Injection Basic Authentication</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-jwt-generation-release-notes">Credential Injection JWT Generation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-release-notes">Credential Injection OAuth 2.0</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-authorization-release-notes">External Authorization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/injection-protection-release-notes">Injection Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-allowlist-release-notes">IP Allowlist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-blocklist-release-notes">IP Blocklist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/json-threat-protection-release-notes">JSON Threat Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/jwt-validation-release-notes">JWT Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-obo-release-notes">OAuth 2.0 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-protected-resource-metadata-release-notes">OAuth 2.0 Protected Resource Metadata</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-token-introspection-release-notes">OAuth 2.0 Token Introspection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/openid-token-enforcement-release-notes">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/schema-validation-release-notes">Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/soap-schema-validation-release-notes">SOAP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-release-notes">Transport Layer Security (TLS) - Inbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-outbound-release-notes">Transport Layer Security (TLS) - Outbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/web-services-security-release-notes">WS-Security</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/xml-threat-protection-release-notes">XML Threat Protection</a></p></td></tr><tr><td rowspan="8"><p><strong>Transformation</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-lambda-release-notes">AWS Lambda</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-body-transformation-release-notes">DataWeave Body Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-headers-transformation-release-notes">DataWeave Headers Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-request-filter-release-notes">DataWeave Request Filter</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-processing-release-notes">External Processing</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-injection-release-notes">Header Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-removal-release-notes">Header Removal</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/javascript-scripting-release-notes">JavaScript Scripting</a></p></td></tr><tr><td rowspan="3"><p><strong>Troubleshooting</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/message-logging-release-notes">Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-message-logging-release-notes">Outbound Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tracing-release-notes">Tracing</a></p></td></tr></tbody></table>

## See Also

- [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.13/gateway-version-lifecycle)

- [Edge and LTS Releases for Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-version-lifecycle#edge-lts)

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=503420434b160b142ea63803097a9b6ef223fa7c9aba97844d96687a9b742453 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-release-notes.md -->

---
product: Omni Gateway
version: 1.9
---

# Omni Gateway Release Notes

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Mulesoft Omni Gateway is an Envoy-based, ultrafast lightweight API gateway designed to manage and
secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD workflows, Omni
Gateway delivers the performance required for the most demanding applications and microservices
while providing enterprise security and manageability across any environment.

The following release notes are provided for Omni Gateway:

- [Omni Gateway Release Notes](https://docs.mulesoft.com/release-notes/gateway/gateway-release-notes)

- [Model Proxy Release Notes](https://docs.mulesoft.com/release-notes/gateway/model-proxy-release-notes)

## Policy Release Notes

The following release notes are provided for Omni Gateway Policies:

<table><colgroup><col> <col></colgroup><thead><tr><th>Category</th><th>Policy</th></tr></thead><tbody><tr><td rowspan="16"><p><strong>A2A</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-agent-card-release-notes">A2A Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-intask-authorization-code-policy-release-notes">A2A In-Task Authorization Code</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/credential-injection-oauth2-obo-release-notes">A2A OAuth2 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-pii-detector-release-notes">A2A PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-prompt-decorator-release-notes">A2A Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-quality-evaluation-release-notes">A2A Quality Evaluation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-schema-validation-release-notes">A2A Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-token-rate-limit-release-notes">A2A Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-agent-card-release-notes">A2A v1 Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-azure-guardrails-release-notes">A2A v1 Azure Content Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-bedrock-guardrails-release-notes">A2A v1 Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-pii-detector-release-notes">A2A v1 PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-prompt-decorator-release-notes">A2A v1 Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-schema-validation-release-notes">A2A v1 Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-to-v03-transcoder-release-notes">A2A v1 to v0.3 Transcoder</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-token-rate-limit-release-notes">A2A v1 Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>A2A and MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/agent-connection-telemetry-release-notes">Agent Connection Telemetry</a></p></td></tr><tr><td rowspan="2"><p><strong>Compliance</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/client-id-enforcement-release-notes">Client ID Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/cors-release-notes">Cross-Origin Resource Sharing (CORS)</a></p></td></tr><tr><td rowspan="5"><p><strong>GraphQL</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-access-control-release-notes">GraphQL Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-introspection-control-release-notes">GraphQL Introspection Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-operation-limits-release-notes">GraphQL Operation Limits</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-schema-validation-release-notes">GraphQL Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-static-query-complexity-release-notes">GraphQL Static Query Complexity</a></p></td></tr><tr><td rowspan="9"><p><strong>LLM</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/bedrock-guardrails-release-notes">Amazon Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/azure-content-safety-release-notes">Azure Content Safety</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/crowdstrike-aidr-guardrails-release-notes">CrowdStrike AIDR Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/f5-guardrails-release-notes">F5 Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/google-model-armor-guardrails-release-notes">Google Model Armor Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-pii-detection-release-notes">LLM PII Detection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-token-rate-limit-release-notes">LLM Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-proxy-request-compression-release-notes">Model Proxy Request Compression</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/regex-prompt-guard-policy-release-notes">Regex Prompt Guard</a></p></td></tr><tr><td rowspan="8"><p><strong>MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-attribute-access-control-release-notes">MCP Attribute-Based Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-global-access-release-notes">MCP Global Access</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-pii-detector-release-notes">MCP PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-payload-optimization-release-notes">MCP Payload Optimization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-progressive-disclosure-release-notes">MCP Tools Progressive Disclosure</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-schema-validation-release-notes">MCP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-support-release-notes">MCP Support</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-tool-mapping-release-notes">MCP Tool Mapping</a></p></td></tr><tr><td rowspan="12"><p><strong>Quality of Service</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-circuit-breaker-release-notes">Circuit Breaker</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/health-check-release-notes">Health Check</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/http-caching-release-notes">HTTP Caching</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-release-notes">Rate Limiting</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-sla-release-notes">Rate Limiting: SLA-based</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/response-timeout-release-notes">Response Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/spike-control-release-notes">Spike Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/stream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-route-release-notes">Traffic Management for Multiple Upstream Services</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-release-notes">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-upstream-idle-timeout-release-notes">Upstream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/websocket-connection-limit-release-notes">WebSocket Connection Limit</a></p></td></tr><tr><td><p><strong>SSE</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/sse-logging-release-notes">SSE Logging</a></p></td></tr><tr><td rowspan="24"><p><strong>Security</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/api-security-identification-header-release-notes">API Security-Identification Header</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-signature-release-notes">AWS Request Signature</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-ldap-release-notes">Basic Authentication: LDAP</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-simple-release-notes">Basic Authentication: Simple</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-api-key-release-notes">Credential Injection API Key</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-basic-auth-release-notes">Credential Injection Basic Authentication</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-jwt-generation-release-notes">Credential Injection JWT Generation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-release-notes">Credential Injection OAuth 2.0</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-authorization-release-notes">External Authorization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/injection-protection-release-notes">Injection Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-allowlist-release-notes">IP Allowlist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-blocklist-release-notes">IP Blocklist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/json-threat-protection-release-notes">JSON Threat Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/jwt-validation-release-notes">JWT Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-obo-release-notes">OAuth 2.0 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-protected-resource-metadata-release-notes">OAuth 2.0 Protected Resource Metadata</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-token-introspection-release-notes">OAuth 2.0 Token Introspection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/openid-token-enforcement-release-notes">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/schema-validation-release-notes">Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/soap-schema-validation-release-notes">SOAP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-release-notes">Transport Layer Security (TLS) - Inbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-outbound-release-notes">Transport Layer Security (TLS) - Outbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/web-services-security-release-notes">WS-Security</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/xml-threat-protection-release-notes">XML Threat Protection</a></p></td></tr><tr><td rowspan="8"><p><strong>Transformation</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-lambda-release-notes">AWS Lambda</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-body-transformation-release-notes">DataWeave Body Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-headers-transformation-release-notes">DataWeave Headers Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-request-filter-release-notes">DataWeave Request Filter</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-processing-release-notes">External Processing</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-injection-release-notes">Header Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-removal-release-notes">Header Removal</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/javascript-scripting-release-notes">JavaScript Scripting</a></p></td></tr><tr><td rowspan="3"><p><strong>Troubleshooting</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/message-logging-release-notes">Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-message-logging-release-notes">Outbound Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tracing-release-notes">Tracing</a></p></td></tr></tbody></table>

## See Also

- [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.9/flex-gateway-version-lifecycle)

- [Edge and LTS Releases for Omni Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-version-lifecycle#edge-lts)

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=6b6fc7ed50ad885601a511a0b135dfa0cf0f43a0850a1446481c07272b029649 url=/mulesoft/current/en-us/gateway/latest/gateway-release-notes.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Omni Gateway Release Notes

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Mulesoft Omni Gateway is an Envoy-based, ultrafast lightweight API gateway designed to manage and
secure APIs running anywhere. Built to seamlessly integrate with DevOps and CI/CD workflows, Omni
Gateway delivers the performance required for the most demanding applications and microservices
while providing enterprise security and manageability across any environment.

The following release notes are provided for Omni Gateway:

- [Omni Gateway Release Notes](https://docs.mulesoft.com/release-notes/gateway/gateway-release-notes)

- [Model Proxy Release Notes](https://docs.mulesoft.com/release-notes/gateway/model-proxy-release-notes)

## Policy Release Notes

The following release notes are provided for Omni Gateway Policies:

<table><colgroup><col> <col></colgroup><thead><tr><th>Category</th><th>Policy</th></tr></thead><tbody><tr><td rowspan="16"><p><strong>A2A</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-agent-card-release-notes">A2A Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-intask-authorization-code-policy-release-notes">A2A In-Task Authorization Code</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/credential-injection-oauth2-obo-release-notes">A2A OAuth2 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-pii-detector-release-notes">A2A PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-prompt-decorator-release-notes">A2A Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-quality-evaluation-release-notes">A2A Quality Evaluation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-schema-validation-release-notes">A2A Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-token-rate-limit-release-notes">A2A Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-agent-card-release-notes">A2A v1 Agent Card</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-azure-guardrails-release-notes">A2A v1 Azure Content Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-bedrock-guardrails-release-notes">A2A v1 Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-pii-detector-release-notes">A2A v1 PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-prompt-decorator-release-notes">A2A v1 Prompt Decorator</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-schema-validation-release-notes">A2A v1 Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-to-v03-transcoder-release-notes">A2A v1 to v0.3 Transcoder</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-token-rate-limit-release-notes">A2A v1 Token Based Rate Limit</a></p></td></tr><tr><td><p><strong>A2A and MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/agent-connection-telemetry-release-notes">Agent Connection Telemetry</a></p></td></tr><tr><td rowspan="2"><p><strong>Compliance</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/client-id-enforcement-release-notes">Client ID Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/cors-release-notes">Cross-Origin Resource Sharing (CORS)</a></p></td></tr><tr><td rowspan="5"><p><strong>GraphQL</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-access-control-release-notes">GraphQL Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-introspection-control-release-notes">GraphQL Introspection Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-operation-limits-release-notes">GraphQL Operation Limits</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-schema-validation-release-notes">GraphQL Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-static-query-complexity-release-notes">GraphQL Static Query Complexity</a></p></td></tr><tr><td rowspan="9"><p><strong>LLM</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/bedrock-guardrails-release-notes">Amazon Bedrock Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/azure-content-safety-release-notes">Azure Content Safety</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/crowdstrike-aidr-guardrails-release-notes">CrowdStrike AIDR Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/f5-guardrails-release-notes">F5 Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/google-model-armor-guardrails-release-notes">Google Model Armor Guardrails</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-pii-detection-release-notes">LLM PII Detection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-token-rate-limit-release-notes">LLM Token Based Rate Limit</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/llm-proxy-request-compression-release-notes">Model Proxy Request Compression</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/regex-prompt-guard-policy-release-notes">Regex Prompt Guard</a></p></td></tr><tr><td rowspan="8"><p><strong>MCP</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-attribute-access-control-release-notes">MCP Attribute-Based Access Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-global-access-release-notes">MCP Global Access</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-pii-detector-release-notes">MCP PII Detector</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-payload-optimization-release-notes">MCP Payload Optimization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-progressive-disclosure-release-notes">MCP Tools Progressive Disclosure</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-schema-validation-release-notes">MCP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-support-release-notes">MCP Support</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-tool-mapping-release-notes">MCP Tool Mapping</a></p></td></tr><tr><td rowspan="12"><p><strong>Quality of Service</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-circuit-breaker-release-notes">Circuit Breaker</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/health-check-release-notes">Health Check</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/http-caching-release-notes">HTTP Caching</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-release-notes">Rate Limiting</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-sla-release-notes">Rate Limiting: SLA-based</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/response-timeout-release-notes">Response Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/spike-control-release-notes">Spike Control</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/stream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-route-release-notes">Traffic Management for Multiple Upstream Services</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-release-notes">Traffic Management for Multiple Upstream Services (Weighted)</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-upstream-idle-timeout-release-notes">Upstream Idle Timeout</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/websocket-connection-limit-release-notes">WebSocket Connection Limit</a></p></td></tr><tr><td><p><strong>SSE</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/sse-logging-release-notes">SSE Logging</a></p></td></tr><tr><td rowspan="24"><p><strong>Security</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/api-security-identification-header-release-notes">API Security-Identification Header</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-signature-release-notes">AWS Request Signature</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-ldap-release-notes">Basic Authentication: LDAP</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/basic-auth-simple-release-notes">Basic Authentication: Simple</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-api-key-release-notes">Credential Injection API Key</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-basic-auth-release-notes">Credential Injection Basic Authentication</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-jwt-generation-release-notes">Credential Injection JWT Generation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-release-notes">Credential Injection OAuth 2.0</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-authorization-release-notes">External Authorization</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/injection-protection-release-notes">Injection Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-allowlist-release-notes">IP Allowlist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/ip-blocklist-release-notes">IP Blocklist</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/json-threat-protection-release-notes">JSON Threat Protection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/jwt-validation-release-notes">JWT Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-obo-release-notes">OAuth 2.0 OBO Credential Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-protected-resource-metadata-release-notes">OAuth 2.0 Protected Resource Metadata</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/oauth-token-introspection-release-notes">OAuth 2.0 Token Introspection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/openid-token-enforcement-release-notes">OpenID Connect OAuth 2.0 Access Token Enforcement</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/schema-validation-release-notes">Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/soap-schema-validation-release-notes">SOAP Schema Validation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-release-notes">Transport Layer Security (TLS) - Inbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-outbound-release-notes">Transport Layer Security (TLS) - Outbound</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/web-services-security-release-notes">WS-Security</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/xml-threat-protection-release-notes">XML Threat Protection</a></p></td></tr><tr><td rowspan="8"><p><strong>Transformation</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-aws-lambda-release-notes">AWS Lambda</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-body-transformation-release-notes">DataWeave Body Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-headers-transformation-release-notes">DataWeave Headers Transformation</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/dataweave-request-filter-release-notes">DataWeave Request Filter</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-processing-release-notes">External Processing</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-injection-release-notes">Header Injection</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/header-removal-release-notes">Header Removal</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/javascript-scripting-release-notes">JavaScript Scripting</a></p></td></tr><tr><td rowspan="3"><p><strong>Troubleshooting</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/message-logging-release-notes">Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-message-logging-release-notes">Outbound Message Logging</a></p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tracing-release-notes">Tracing</a></p></td></tr></tbody></table>

## See Also

- [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/latest/gateway-version-lifecycle)

- [Edge and LTS Releases for Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-version-lifecycle#edge-lts)

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=8233f47167d8895638d27192e2358ae3104c4856fad1b1f4c3202aeaa8d14eba url=/mulesoft/current/en-us/gateway/1.13/gateway-version-lifecycle.md -->

---
product: Omni Gateway
version: 1.13
---

# Omni Gateway Version Lifecycle

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Starting with Omni Gateway 1.9, MuleSoft introduces two new release channels, Edge and Long-term
Support (LTS). These release channels are available for both Managed and Self-Managed Omni Gateway.

## Edge and LTS Releases for Omni Gateway

Consider the information in this table to determine which release channel best suits your
requirements.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Channel Type</th><th>Release Cadence</th><th>Differentiators</th><th>Support Coverage</th></tr></thead><tbody><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>Three times per year</p></div><div><ul><li><p>May</p></li><li><p>August</p></li><li><p>November</p></li></ul></div></div></td><td><div><div><p>Includes new features more often and has a shorter support period for each release.</p></div></div></td><td><div><div><p>Omni Gateway 1.9 and later</p></div><div><ul><li><p>Five months Standard Support</p></li><li><p>Three months Extended Support</p></li></ul></div><div><p>Omni Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr><tr><td><div><div><p><strong>LTS</strong></p></div></div></td><td><div><div><p>Once a year</p></div><div><ul><li><p>February</p></li></ul></div></div></td><td><div><div><p>Bundles new features in an annual release and has a longer support period for each release.</p></div></div></td><td><div><div><p>Omni Gateway 1.9 and later</p></div><div><ul><li><p>Eighteen months Standard Support</p></li><li><p>Six months Extended Support</p></li></ul></div><div><p>Omni Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr></tbody></table>

> [!NOTE] Release dates are subject to change due to product needs.

For detailed information and support timeframes for Omni Gateway 1.8 and earlier, see the
[MuleSoft Support Policy](https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Omni Gateway Version Support

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Omni Gateway Version</th><th>Release Date</th><th>End of Standard Support</th><th>End of Extended Support</th></tr></thead><tbody><tr><td><div><div><p>1.14.0 Edge</p></div></div></td><td><div><div><p>August 27, 2026</p></div></div></td><td><div><div><p>January 27, 2027</p></div></div></td><td><div><div><p>April 27, 2027</p></div></div></td></tr><tr><td><div><div><p>1.13.0 Edge</p></div></div></td><td><div><div><p>May 11, 2026</p></div></div></td><td><div><div><p>October 11, 2026</p></div></div></td><td><div><div><p>January 11, 2027</p></div></div></td></tr><tr><td><div><div><p>1.12.0 LTS</p></div></div></td><td><div><div><p>February 25, 2026</p></div></div></td><td><div><div><p>August 25, 2027</p></div></div></td><td><div><div><p>February 25, 2028</p></div></div></td></tr><tr><td><div><div><p>1.11.0 Edge</p></div></div></td><td><div><div><p>October 15, 2025</p></div></div></td><td><div><div><p>March 15, 2026</p></div></div></td><td><div><div><p>June 15, 2026</p></div></div></td></tr><tr><td><div><div><p>1.10.0 Edge</p></div></div></td><td><div><div><p>June 27, 2025</p></div></div></td><td><div><div><p>November 27, 2025</p></div></div></td><td><div><div><p>February 27, 2026</p></div></div></td></tr><tr><td><div><div><p>1.9.0 LTS</p></div></div></td><td><div><div><p>March 18, 2025</p></div></div></td><td><div><div><p>September 18, 2026</p></div></div></td><td><div><div><p>March 18, 2027</p></div></div></td></tr></tbody></table>

## Deployment Models and Lifecycle Management

Omni Gateway lifecycle management varies depending on the release channel and the type of gateway.
Managed Omni Gateway instances are auto-upgraded regularly, and any available patches are applied
once a month. Self-managed gateways are never patched or upgraded automatically.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Managed Gateway</th><th>Self-Managed Gateway</th></tr></thead><tbody><tr><td><div><div><p>Auto-upgrade</p></div></div></td><td><div><div><p>Managed Gateways are auto-upgraded to the latest minor version within their respective channels (Edge or LTS).</p></div><div><ul><li><p>Edge: Three times per year</p></li><li><p>LTS: Once a year</p></li></ul></div></div></td><td><div><div><p>No auto-upgrade capabilities</p></div></div></td></tr><tr><td><div><div><p>Patches</p></div></div></td><td><div><div><p>Monthly auto-patching</p></div></div></td><td><div><div><p>Available for Omni Gateway versions that are within the support period for their respective channels (Edge or LTS).</p></div></div></td></tr><tr><td><div><div><p>Self-upgrade</p></div></div></td><td><div><div><p>You can manually upgrade to the latest version that matches your release channel (Edge or LTS) before the scheduled automatic upgrade.</p></div></div></td><td><div><div><p>Always available</p></div></div></td></tr><tr><td><div><div><p>Rollback</p></div></div></td><td><div><div><p>You can revert to the previous version if it’s still within the release channel support period.</p></div></div></td><td><div><div><p>Available to the previously used version</p></div></div></td></tr><tr><td><div><div><p>Restart</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Keep running</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Supportability</p></div></div></td><td><div><div><p>Standard Support (auto-upgrade ensures that managed gateways are always on the latest Edge or LTS version).</p></div></div></td><td><div><div><p>Until End of Extended Support. See the <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a> for more information.</p></div></div></td></tr></tbody></table>

For information on patching, upgrading, rolling back, or deleting a gateway, see
[Maintaining an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-maintain).

<!-- document id=23b3bada6267dc8dce9b3d199f7d863065dff871d034638404acf71cddb0a369 url=/mulesoft/current/en-us/gateway/latest/gateway-version-lifecycle.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Omni Gateway Version Lifecycle

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Starting with Omni Gateway 1.9, MuleSoft introduces two new release channels, Edge and Long-term
Support (LTS). These release channels are available for both Managed and Self-Managed Omni Gateway.

## Edge and LTS Releases for Omni Gateway

Consider the information in this table to determine which release channel best suits your
requirements.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Channel Type</th><th>Release Cadence</th><th>Differentiators</th><th>Support Coverage</th></tr></thead><tbody><tr><td><div><div><p><strong>Edge</strong></p></div></div></td><td><div><div><p>Three times per year</p></div><div><ul><li><p>May</p></li><li><p>August</p></li><li><p>November</p></li></ul></div></div></td><td><div><div><p>Includes new features more often and has a shorter support period for each release.</p></div></div></td><td><div><div><p>Omni Gateway 1.9 and later</p></div><div><ul><li><p>Five months Standard Support</p></li><li><p>Three months Extended Support</p></li></ul></div><div><p>Omni Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr><tr><td><div><div><p><strong>LTS</strong></p></div></div></td><td><div><div><p>Once a year</p></div><div><ul><li><p>February</p></li></ul></div></div></td><td><div><div><p>Bundles new features in an annual release and has a longer support period for each release.</p></div></div></td><td><div><div><p>Omni Gateway 1.9 and later</p></div><div><ul><li><p>Eighteen months Standard Support</p></li><li><p>Six months Extended Support</p></li></ul></div><div><p>Omni Gateway 1.8 and earlier</p></div><div><ul><li><p>See <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a>.</p></li></ul></div></div></td></tr></tbody></table>

> [!NOTE] Release dates are subject to change due to product needs.

For detailed information and support timeframes for Omni Gateway 1.8 and earlier, see the
[MuleSoft Support Policy](https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf).

## Omni Gateway Version Support

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Omni Gateway Version</th><th>Release Date</th><th>End of Standard Support</th><th>End of Extended Support</th></tr></thead><tbody><tr><td><div><div><p>1.14.0 Edge</p></div></div></td><td><div><div><p>August 27, 2026</p></div></div></td><td><div><div><p>January 27, 2027</p></div></div></td><td><div><div><p>April 27, 2027</p></div></div></td></tr><tr><td><div><div><p>1.13.0 Edge</p></div></div></td><td><div><div><p>May 11, 2026</p></div></div></td><td><div><div><p>October 11, 2026</p></div></div></td><td><div><div><p>January 11, 2027</p></div></div></td></tr><tr><td><div><div><p>1.12.0 LTS</p></div></div></td><td><div><div><p>February 25, 2026</p></div></div></td><td><div><div><p>August 25, 2027</p></div></div></td><td><div><div><p>February 25, 2028</p></div></div></td></tr><tr><td><div><div><p>1.11.0 Edge</p></div></div></td><td><div><div><p>October 15, 2025</p></div></div></td><td><div><div><p>March 15, 2026</p></div></div></td><td><div><div><p>June 15, 2026</p></div></div></td></tr><tr><td><div><div><p>1.10.0 Edge</p></div></div></td><td><div><div><p>June 27, 2025</p></div></div></td><td><div><div><p>November 27, 2025</p></div></div></td><td><div><div><p>February 27, 2026</p></div></div></td></tr><tr><td><div><div><p>1.9.0 LTS</p></div></div></td><td><div><div><p>March 18, 2025</p></div></div></td><td><div><div><p>September 18, 2026</p></div></div></td><td><div><div><p>March 18, 2027</p></div></div></td></tr></tbody></table>

## Deployment Models and Lifecycle Management

Omni Gateway lifecycle management varies depending on the release channel and the type of gateway.
Managed Omni Gateway instances are auto-upgraded regularly, and any available patches are applied
once a month. Self-managed gateways are never patched or upgraded automatically.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Action</th><th>Managed Gateway</th><th>Self-Managed Gateway</th></tr></thead><tbody><tr><td><div><div><p>Auto-upgrade</p></div></div></td><td><div><div><p>Managed Gateways are auto-upgraded to the latest minor version within their respective channels (Edge or LTS).</p></div><div><ul><li><p>Edge: Three times per year</p></li><li><p>LTS: Once a year</p></li></ul></div></div></td><td><div><div><p>No auto-upgrade capabilities</p></div></div></td></tr><tr><td><div><div><p>Patches</p></div></div></td><td><div><div><p>Monthly auto-patching</p></div></div></td><td><div><div><p>Available for Omni Gateway versions that are within the support period for their respective channels (Edge or LTS).</p></div></div></td></tr><tr><td><div><div><p>Self-upgrade</p></div></div></td><td><div><div><p>You can manually upgrade to the latest version that matches your release channel (Edge or LTS) before the scheduled automatic upgrade.</p></div></div></td><td><div><div><p>Always available</p></div></div></td></tr><tr><td><div><div><p>Rollback</p></div></div></td><td><div><div><p>You can revert to the previous version if it’s still within the release channel support period.</p></div></div></td><td><div><div><p>Available to the previously used version</p></div></div></td></tr><tr><td><div><div><p>Restart</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Keep running</p></div></div></td><td><div><div><p>Always</p></div></div></td><td><div><div><p>Until End of Extended Support</p></div></div></td></tr><tr><td><div><div><p>Supportability</p></div></div></td><td><div><div><p>Standard Support (auto-upgrade ensures that managed gateways are always on the latest Edge or LTS version).</p></div></div></td><td><div><div><p>Until End of Extended Support. See the <a href="https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/Agreements/versioning-back-support-policy.pdf">MuleSoft Support Policy</a> for more information.</p></div></div></td></tr></tbody></table>

For information on patching, upgrading, rolling back, or deleting a gateway, see
[Maintaining an Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-maintain).

<!-- document id=23a508de100cdd3152087d57b83869e33fe5feb2605f9bc119442b24289616b8 url=/mulesoft/current/en-us/gateway/1.12/policies-included-openid-token-enforcement.md -->

---
product: Omni Gateway
version: 1.12
keywords: open, id, oauth 2.0, token, enforcement, api gateway, flex gateway, gateway, policy
---

# OpenID Connect OAuth 2.0 Token Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OpenID Connect OAuth 2.0 Token Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server</p></td></tr></tbody></table>

## Summary

The OpenID Connect Access Token Enforcement policy restricts access to a protected resource to only
those HTTP requests that provide a valid Oauth2 token belonging to a client application with API
access. The policy does not generate tokens but only validates them.

This policy is available only to an organization that is configured to use the OpenID Connect
dynamic client registration as a
[client-management solution](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).

## Configuring Policy Parameters

### Flex Gateway Local Mode

The OpenID Connect Access Token Enforcement policy doesn’t support in Flex Gateway running in Local
Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p>Scopes</p></td><td><p>Displays a space-separated list of supported scopes.</p></td><td><p>READ, WRITE, READ and WRITE</p></td></tr><tr><td><p>Scope Validation Criteria</p></td><td><p>Determines if the token must contain all defined scopes or just one. The values are <code>Contains all scopes</code> and <code>Contains any scope</code>.</p></td><td><p>If the 'Contains all scopes' value is selected, the tokens with the scopes <code>READ</code> and <code>WRITE</code> are accepted. If the 'Contains any scopes' value is selected, the tokens with the scopes <code>READ, WRITE, and READ AND WRITE</code> are accepted.</p></td></tr><tr><td><p>Expose Headers</p></td><td><p>In a proxy scenario, specifies whether headers must be exposed in the request to the backend. User properties returned by the federation server are prefixed with 'X-AGW-' and sent as headers to the backend.</p></td><td></td></tr><tr><td><p>Skip Client Id Validation</p></td><td><p>Skips the client application’s API contract validation.</p></td><td><p>If selected, Step 4 of the diagram in the <a href="#how-this-policy-works">How This Policy Works</a> section is skipped.</p></td></tr><tr><td><p>Authentication request timeout</p></td><td><p>Sets the maximum time, in milliseconds, to wait for a response when authenticating with the Access Token validation endpoint.</p></td><td><p><code>10000</code></p></td></tr><tr><td><p>Enable Protected Resource Metadata</p></td><td><p>Enables <a href="https://www.rfc-editor.org/rfc/rfc9728">RFC 9728</a> OAuth 2.0 Protected Resource Metadata. When enabled, all <code>401</code> responses include a <code>WWW-Authenticate</code> header with the resource metadata URL <code>{api_path}/.well-known/oauth-protected-resource</code>.<br>When a client makes a GET request to this path, Flex Gateway responds with a JSON document containing the authorization server metadata. By default, Flex Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, <code><a href="https://auth.example.com/introspect">https://auth.example.com/introspect</a></code> becomes <code><a href="https://auth.example.com">https://auth.example.com</a></code>.</p></td><td></td></tr><tr><td><p>Override Protected Resource Metadata Authorization Server Url</p></td><td><p>Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.</p></td><td></td></tr><tr><td><p>Protected Resource Metadata Authorization Server Url</p></td><td><p>Server base URL to use when <code>overrideProtectedResourceMetadataAuthorizationServerUrl</code> is enabled.</p></td><td></td></tr></tbody></table>

## How This Policy Works

The following diagram illustrates the OpenID Connect Access Token Enforcement policy workflow:

![A flowchart illustrating the process of a user engaging with an API via a PingFederate policy](/mulesoft/current/en-us/gateway/1.12/_images/open-id-policy-workflow.png)

As shown in the diagram:

1.  The user first sends an HTTP request to the API protected by the policy.

2.  The policy extracts the token from the request and sends it to the validation endpoint to verify
    the integrity of the token.

3.  The token validation endpoint returns token metadata, including the client ID of the client
    application.

4.  Using a local database updated with contracts previously obtained from Anypoint Platform, the
    policy verifies whether the client ID has access to the API.

5.  If all the validations are successfully completed, the request is allowed to reach the backend.

### Leveraging Token Validation Endpoint Information

When a token validation endpoint successfully validates a token, certain information, such as
configurable fields from OpenID Connect, are returned to the policy.

The following example illustrates the token validation response from the authorization server:

```text
{
    "uid":"john.doe",
    "mail":"john.doe@example.com"
    "token_type":"Bearer",
    "exp": 1516239022
    "alias" : ["Jhon", "Jhonny", "Mr Doe"],
    "address" : {
        "city": "london",
        "road": “abbey road"
    }
}
```

The fields returned by the OAuth provider are processed by the policy, propagated throughout the
flow, and finally exposed to the backend if the application requesting the access uses an HTTP
requester.

### Token Caching in Local Mode

After the system validates a token, that token is cached (by default), until it expires, thereby
improving the performance of the policy. In certain cases, such as in the case of revoked tokens,
you might want to minimize or even disable caching.

The validation endpoint sends multiple properties to the policy, including the expiration time of
the token. If the expiration information is not available, tokens are not cached.

To control the time taken to cache the tokens, before you attempt revalidating against the token
validation endpoint, configure the following parameter in your declarative configuration file:

- policyRef: name: openidconnect-access-token-enforcement-flex config: ...
  maxFederationExpirationTime: <expiration time in seconds>

Setting this property caches the token for the specified amount of time or until the tokens expire,
whichever occurs first. If you have enabled this property and the validation endpoint does not send
the expiration information, tokens are not cached.

To control the number of tokens that can be cached simultaneously, configure the following parameter
in your declarative configuration file.

- policyRef: name: openidconnect-access-token-enforcement-flex config: ... maxCacheSize: <amount of
  tokens to be cached; default value is 1.000; specify 0 to disable caching>

### Token Validation Endpoint Authentication

To complete validating the provided token, the policy sends a request to the validation endpoint.
The policy then obtains the credentials from the client provider configuration in access management,
per the Token Introspection Client section of the OAuth 2.0 Authorization Framework specification.
These credentials are sent in the request body, as specified in the
[Client Authentication section of the OAuth 2.0 Authorization Framework specification](https://tools.ietf.org/html/rfc6749#section-2.3).

Other authentication methods for the token validation endpoint are currently not supported.

## Configuring the Expose Headers Option

If you configured the `Expose Headers` option in the policy and if the application (for example,
out-of-the-box proxies) uses the HTTP requester, the properties are redirected to the backend as
headers.

For each field, the original request to the protected resource is enriched with the HTTP headers
using the format: X-AGW- + <key>=<value>. For the example response from the previous section, the
following headers are added:

```text
X-AGW-uid=john.doe
X-AGW-mail=john.doe@example.com
X-AGW-token_type=Bearer
```

The propagated properties do not include the `scope`, and `exp` objects and arrays.

For further processing within the flow, the original unparsed response from the validation endpoint
is made available. The information is stored in an authentication object.

For example, if a `mail` field is returned to the policy, you can access the value of the field by
using the following DataWeave 2.0 expression:

`#[authentication.properties.userProperties.mail]`

You can obtain the client ID of the OAuth2 token by using the following DataWeave 2.0 expression:

`#[authentication.principal]`

## FAQs

**The OpenID Connect Access Token Enforcement policy does not appear in the list of policies to
apply to the API.**

If the policy does not appear in the policies list, ensure that you have configured the OpenID
client provider in Access Management. For information, see
[Configure OpenID Connect Client Management](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).
If you are using [multiple IdPs](https://docs.mulesoft.com/api-manager/latest/configure-multiple-credential-providers),
verify that the OpenID connect client is properly configured in the API.

**Can I generate OAuth 2.0 tokens with the policy?**

No. The policy only validates the tokens.

**How are the OAuth tokens cached?**

OAuth 2.0 tokens are cached only in memory and are never written to disk.

**Can I configure the Rate-Limiting SLA policy after I configure the OpenID Connect Access Token
Enforcement policy?**

Yes, you can. Apply the Rate-Limiting SLA policy after the OpenID Connect Access Token Enforcement
policy and provide a `Client ID Expression` value using the following DataWeave 2.0 expression:

`#[authentication.principal]`

Because the identity of the requester is already validated by the OpenID Connect Access Token
Enforcement policy, you can leave the `Client Secret Expression` field empty.

<!-- document id=c9397f2a6fd25e37458fbf535b5fb503fbd7195f2a8f465fdf11b6aeccc22bbc url=/mulesoft/current/en-us/gateway/1.13/policies-included-openid-token-enforcement.md -->

---
product: Omni Gateway
version: 1.13
keywords: open, id, oauth 2.0, token, enforcement, api gateway, flex gateway, gateway, policy
---

# OpenID Connect OAuth 2.0 Token Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OpenID Connect OAuth 2.0 Token Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/openid-token-enforcement-release-notes">OpenID Connect OAuth 2.0 Token Enforcement</a></p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server</p></td></tr></tbody></table>

## Summary

The OpenID Connect Access Token Enforcement policy restricts access to a protected resource to only
those HTTP requests that provide a valid Oauth2 token belonging to a client application with API
access. The policy does not generate tokens but only validates them.

This policy is available only to an organization that is configured to use the OpenID Connect
dynamic client registration as a
[client-management solution](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The OpenID Connect Access Token Enforcement policy doesn’t support in Omni Gateway running in Local
Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Scopes</p></div></div></td><td><div><div><p>Displays a space-separated list of supported scopes.</p></div></div></td><td><div><div><p>READ, WRITE, READ and WRITE</p></div></div></td></tr><tr><td><div><div><p>Scope Validation Criteria</p></div></div></td><td><div><div><p>Determines if the token must contain all defined scopes or just one. The values are <strong>Contains all scopes</strong> and <strong>Contains any scope</strong>.</p></div><div><p>For <strong>Contains all scopes</strong>, the policy only accepts tokens with both the <code>READ</code> and <code>WRITE</code> scopes. For <strong>Contains any scopes</strong>, the policy accepts tokens with at least one scope. If no scopes are defined for the <strong>Scopes</strong> parameter, the policy doesn’t validate scopes regardless of what you select for <strong>Scope Validation Criteria</strong>.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>In a proxy scenario, specifies whether headers must be exposed in the request to the backend. User properties returned by the federation server are prefixed with 'X-AGW-' and sent as headers to the backend.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Skip Client Id Validation</p></div></div></td><td><div><div><p>Skips the client application’s API contract validation.</p></div></div></td><td><div><div><p>If selected, Step 4 of the diagram in the <a href="#how-this-policy-works">How This Policy Works</a> section is skipped.</p></div></div></td></tr><tr><td><div><div><p>Authentication request timeout</p></div></div></td><td><div><div><p>Sets the maximum time, in milliseconds, to wait for a response when authenticating with the Access Token validation endpoint.</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr><tr><td><div><div><p>Enable Protected Resource Metadata</p></div></div></td><td><div><div><p>Enables <a href="https://www.rfc-editor.org/rfc/rfc9728">RFC 9728</a> OAuth 2.0 Protected Resource Metadata. When enabled, all <code>401</code> responses include a <code>WWW-Authenticate</code> header with the resource metadata URL <code>{api_path}/.well-known/oauth-protected-resource</code>.<br>When a client makes a GET request to this path, Omni Gateway responds with a JSON document containing the authorization server metadata. By default, Omni Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, <code><a href="https://auth.example.com/introspect">https://auth.example.com/introspect</a></code> becomes <code><a href="https://auth.example.com">https://auth.example.com</a></code>.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Override Protected Resource Metadata Authorization Server Url</p></div></div></td><td><div><div><p>Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Protected Resource Metadata Authorization Server Url</p></div></div></td><td><div><div><p>Server base URL to use when <code>overrideProtectedResourceMetadataAuthorizationServerUrl</code> is enabled.</p></div></div></td><td><div></div></td></tr></tbody></table>

## How This Policy Works

The following diagram illustrates the OpenID Connect Access Token Enforcement policy workflow:

![A flowchart illustrating the process of a user engaging with an API via a PingFederate policy](/mulesoft/current/en-us/gateway/1.13/_images/open-id-policy-workflow.png)

As shown in the diagram:

1.  The user first sends an HTTP request to the API protected by the policy.

2.  The policy extracts the token from the request and sends it to the validation endpoint to verify
    the integrity of the token.

3.  The token validation endpoint returns token metadata, including the client ID of the client
    application.

4.  Using a local database updated with contracts previously obtained from Anypoint Platform, the
    policy verifies whether the client ID has access to the API.

5.  If all the validations are successfully completed, the request is allowed to reach the backend.

### Leveraging Token Validation Endpoint Information

When a token validation endpoint successfully validates a token, certain information, such as
configurable fields from OpenID Connect, are returned to the policy.

The following example illustrates the token validation response from the authorization server:

```text
{
    "uid":"john.doe",
    "mail":"john.doe@example.com"
    "token_type":"Bearer",
    "exp": 1516239022
    "alias" : ["Jhon", "Jhonny", "Mr Doe"],
    "address" : {
        "city": "london",
        "road": “abbey road"
    }
}
```

The fields returned by the OAuth provider are processed by the policy, propagated throughout the
flow, and finally exposed to the backend if the application requesting the access uses an HTTP
requester.

### Token Caching in Local Mode

After the system validates a token, that token is cached (by default), until it expires, thereby
improving the performance of the policy. In certain cases, such as in the case of revoked tokens,
you might want to minimize or even disable caching.

The validation endpoint sends multiple properties to the policy, including the expiration time of
the token. If the expiration information is not available, tokens are not cached.

To control the time taken to cache the tokens, before you attempt revalidating against the token
validation endpoint, configure the following parameter in your declarative configuration file:

- policyRef: name: openidconnect-access-token-enforcement-flex config: ...
  maxFederationExpirationTime: <expiration time in seconds>

Setting this property caches the token for the specified amount of time or until the tokens expire,
whichever occurs first. If you have enabled this property and the validation endpoint does not send
the expiration information, tokens are not cached.

To control the number of tokens that can be cached simultaneously, configure the following parameter
in your declarative configuration file.

- policyRef: name: openidconnect-access-token-enforcement-flex config: ... maxCacheSize: <amount of
  tokens to be cached; default value is 1.000; specify 0 to disable caching>

### Token Validation Endpoint Authentication

To complete validating the provided token, the policy sends a request to the validation endpoint.
The policy then obtains the credentials from the client provider configuration in access management,
per the Token Introspection Client section of the OAuth 2.0 Authorization Framework specification.
These credentials are sent in the request body, as specified in the
[Client Authentication section of the OAuth 2.0 Authorization Framework specification](https://tools.ietf.org/html/rfc6749#section-2.3).

Other authentication methods for the token validation endpoint are currently not supported.

## Configuring the Expose Headers Option

If you configured the `Expose Headers` option in the policy and if the application (for example,
out-of-the-box proxies) uses the HTTP requester, the properties are redirected to the backend as
headers.

For each field, the original request to the protected resource is enriched with the HTTP headers
using the format: X-AGW- + <key>=<value>. For the example response from the previous section, the
following headers are added:

```text
X-AGW-uid=john.doe
X-AGW-mail=john.doe@example.com
X-AGW-token_type=Bearer
```

The propagated properties do not include the `scope`, and `exp` objects and arrays.

For further processing within the flow, the original unparsed response from the validation endpoint
is made available. The information is stored in an authentication object.

For example, if a `mail` field is returned to the policy, you can access the value of the field by
using the following DataWeave 2.0 expression:

`#[authentication.properties.userProperties.mail]`

You can obtain the client ID of the OAuth2 token by using the following DataWeave 2.0 expression:

`#[authentication.principal]`

## FAQs

**The OpenID Connect Access Token Enforcement policy does not appear in the list of policies to
apply to the API.**

If the policy does not appear in the policies list, ensure that you have configured the OpenID
client provider in Access Management. For information, see
[Configure OpenID Connect Client Management](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).
If you are using [multiple IdPs](https://docs.mulesoft.com/api-manager/latest/configure-multiple-credential-providers),
verify that the OpenID connect client is properly configured in the API.

**Can I generate OAuth 2.0 tokens with the policy?**

No. The policy only validates the tokens.

**How are the OAuth tokens cached?**

OAuth 2.0 tokens are cached only in memory and are never written to disk.

**Can I configure the Rate-Limiting SLA policy after I configure the OpenID Connect Access Token
Enforcement policy?**

Yes, you can. Apply the Rate-Limiting SLA policy after the OpenID Connect Access Token Enforcement
policy and provide a `Client ID Expression` value using the following DataWeave 2.0 expression:

`#[authentication.principal]`

Because the identity of the requester is already validated by the OpenID Connect Access Token
Enforcement policy, you can leave the `Client Secret Expression` field empty.

<!-- document id=3527622538b5f71e689eeabbca423bdf87ca33bc2f18dc1103d9453e8891d560 url=/mulesoft/current/en-us/gateway/1.9/policies-included-openid-token-enforcement.md -->

---
product: Omni Gateway
version: 1.9
keywords: open, id, oauth 2.0, token, enforcement, api gateway, flex gateway, gateway, policy
---

# OpenID Connect OAuth 2.0 Token Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OpenID Connect OAuth 2.0 Token Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server</p></td></tr></tbody></table>

## Summary

The OpenID Connect Access Token Enforcement policy restricts access to a protected resource to only
those HTTP requests that provide a valid Oauth2 token belonging to a client application with API
access. The policy does not generate tokens but only validates them.

This policy is available only to an organization that is configured to use the OpenID Connect
dynamic client registration as a
[client-management solution](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: openidconnect-access-token-enforcement-flex config: authenticationTimeout: <int>
// OPTIONAL, default: 10000 scopes: <string> // OPTIONAL, default: "" secureTrustStore: <bool> //
OPTIONAL, default: false scopeValidationCriteria: <string> // OPTIONAL, default: "AND"
exposeHeaders: <bool> // OPTIONAL, default: false skipClientIdValidation: <bool> // OPTIONAL,
default: true maxFederationExpirationTime: <int> // OPTIONAL, default: -1 maxCacheSize: <int> //
OPTIONAL, default: 1000

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>authenticationTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>scopes</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>An empty string</p></div></div></td><td><div><div><p>A space-separated list of supported scopes: <code>read</code> <code>write</code></p></div></div></td></tr><tr><td><div><div><p><code>secureTrustStore</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>scopeValidationCriteria</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"AND"</p></div></div></td><td><div><div><p>Determines if the token must contain all defined scopes or just one</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>In a proxy scenario, this specifies whether headers must be exposed in the request to the backend. User properties returned by the federation server are prefixed with 'X-AGW-' and sent as headers to the backend.</p></div><div><p>See <a href="#leveraging-TVE-information">Leveraging Token Validation Endpoint Information</a> for more information about this parameter.</p></div></div></td></tr><tr><td><div><div><p><code>skipClientIdValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Skips the client application’s API contract validation. If <code>true</code>, Step 4 of the diagram in the <a href="#how-this-policy-works">How This Policy Works</a> section is skipped.</p></div></div></td></tr><tr><td><div><div><p><code>maxFederationExpirationTime</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Max Expiration time in seconds.</p></div><div><p>See <a href="#token-caching">Token Caching</a> for more information about this parameter.</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheSize</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>Amount of tokens to be cached.</p></div><div><p>See <a href="#token-caching">Token Caching</a> for more information about this parameter.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: openidconnect-access-token-enforcement-flex config: authenticationTimeout: 10000
scopes: read write secureTrustStore: false scopeValidationCriteria: OR exposeHeaders: true
skipClientIdValidation: false

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p>Scopes</p></td><td><p>Displays a space-separated list of supported scopes.</p></td><td><p>READ, WRITE, READ and WRITE</p></td></tr><tr><td><p>Scope Validation Criteria</p></td><td><p>Determines if the token must contain all defined scopes or just one. The values are <code>Contains all scopes</code> and <code>Contains any scope</code>.</p></td><td><p>If the 'Contains all scopes' value is selected, the tokens with the scopes <code>READ</code> and <code>WRITE</code> are accepted. If the 'Contains any scopes' value is selected, the tokens with the scopes <code>READ, WRITE, and READ AND WRITE</code> are accepted.</p></td></tr><tr><td><p>Expose Headers</p></td><td><p>In a proxy scenario, specifies whether headers must be exposed in the request to the backend. User properties returned by the federation server are prefixed with 'X-AGW-' and sent as headers to the backend.</p></td><td></td></tr><tr><td><p>Skip Client Id Validation</p></td><td><p>Skips the client application’s API contract validation.</p></td><td><p>If selected, Step 4 of the diagram in the <a href="#how-this-policy-works">How This Policy Works</a> section is skipped.</p></td></tr><tr><td><p>Authentication request timeout</p></td><td><p>Sets the maximum time, in milliseconds, to wait for a response when authenticating with the Access Token validation endpoint.</p></td><td><p><code>10000</code></p></td></tr></tbody></table>

## How This Policy Works

The following diagram illustrates the OpenID Connect Access Token Enforcement policy workflow:

![A flowchart illustrating the process of a user engaging with an API via a PingFederate policy](/mulesoft/current/en-us/gateway/1.9/_images/open-id-policy-workflow.png)

As shown in the diagram:

1.  The user first sends an HTTP request to the API protected by the policy.

2.  The policy extracts the token from the request and sends it to the validation endpoint to verify
    the integrity of the token.

3.  The token validation endpoint returns token metadata, including the client ID of the client
    application.

4.  Using a local database updated with contracts previously obtained from Anypoint Platform, the
    policy verifies whether the client ID has access to the API.

5.  If all the validations are successfully completed, the request is allowed to reach the backend.

### Leveraging Token Validation Endpoint Information

When a token validation endpoint successfully validates a token, certain information, such as
configurable fields from OpenID Connect, are returned to the policy.

The following example illustrates the token validation response from the authorization server:

```text
{
    "uid":"john.doe",
    "mail":"john.doe@example.com"
    "token_type":"Bearer",
    "exp": 1516239022
    "alias" : ["Jhon", "Jhonny", "Mr Doe"],
    "address" : {
        "city": "london",
        "road": “abbey road"
    }
}
```

The fields returned by the OAuth provider are processed by the policy, propagated throughout the
flow, and finally exposed to the backend if the application requesting the access uses an HTTP
requester.

### Token Caching in Local Mode

After the system validates a token, that token is cached (by default), until it expires, thereby
improving the performance of the policy. In certain cases, such as in the case of revoked tokens,
you might want to minimize or even disable caching.

The validation endpoint sends multiple properties to the policy, including the expiration time of
the token. If the expiration information is not available, tokens are not cached.

To control the time taken to cache the tokens, before you attempt revalidating against the token
validation endpoint, configure the following parameter in your declarative configuration file:

- policyRef: name: openidconnect-access-token-enforcement-flex config: ...
  maxFederationExpirationTime: <expiration time in seconds>

Setting this property caches the token for the specified amount of time or until the tokens expire,
whichever occurs first. If you have enabled this property and the validation endpoint does not send
the expiration information, tokens are not cached.

To control the number of tokens that can be cached simultaneously, configure the following parameter
in your declarative configuration file.

- policyRef: name: openidconnect-access-token-enforcement-flex config: ... maxCacheSize: <amount of
  tokens to be cached; default value is 1.000; specify 0 to disable caching>

### Token Validation Endpoint Authentication

To complete validating the provided token, the policy sends a request to the validation endpoint.
The policy then obtains the credentials from the client provider configuration in access management,
per the Token Introspection Client section of the OAuth 2.0 Authorization Framework specification.
These credentials are sent in the request body, as specified in the
[Client Authentication section of the OAuth 2.0 Authorization Framework specification](https://datatracker.ietf.org/doc/html/rfc6749).

Other authentication methods for the token validation endpoint are currently not supported.

## Configuring the Expose Headers Option

If you configured the `Expose Headers` option in the policy and if the application (for example,
out-of-the-box proxies) uses the HTTP requester, the properties are redirected to the backend as
headers.

For each field, the original request to the protected resource is enriched with the HTTP headers
using the format: X-AGW- + <key>=<value>. For the example response from the previous section, the
following headers are added:

```text
X-AGW-uid=john.doe
X-AGW-mail=john.doe@example.com
X-AGW-token_type=Bearer
```

The propagated properties do not include the `scope`, and `exp` objects and arrays.

For further processing within the flow, the original unparsed response from the validation endpoint
is made available. The information is stored in an authentication object.

For example, if a `mail` field is returned to the policy, you can access the value of the field by
using the following DataWeave 2.0 expression:

`#[authentication.properties.userProperties.mail]`

You can obtain the client ID of the OAuth2 token by using the following DataWeave 2.0 expression:

`#[authentication.principal]`

## FAQs

**The OpenID Connect Access Token Enforcement policy does not appear in the list of policies to
apply to the API.**

If the policy does not appear in the policies list, ensure that you have configured the OpenID
client provider in Access Management. For information, see
[Configure OpenID Connect Client Management](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).
If you are using [multiple IdPs](https://docs.mulesoft.com/api-manager/latest/configure-multiple-credential-providers),
verify that the OpenID connect client is properly configured in the API.

**Can I generate OAuth 2.0 tokens with the policy?**

No. The policy only validates the tokens.

**How are the OAuth tokens cached?**

OAuth 2.0 tokens are cached only in memory and are never written to disk.

**Can I configure the Rate-Limiting SLA policy after I configure the OpenID Connect Access Token
Enforcement policy?**

Yes, you can. Apply the Rate-Limiting SLA policy after the OpenID Connect Access Token Enforcement
policy and provide a `Client ID Expression` value using the following DataWeave 2.0 expression:

`#[authentication.principal]`

Because the identity of the requester is already validated by the OpenID Connect Access Token
Enforcement policy, you can leave the `Client Secret Expression` field empty.

<!-- document id=3cb8569e561e3c2efcbdaf5b5a2d4fe68c7975df57b085ccc6a460ea84886e20 url=/mulesoft/current/en-us/gateway/latest/policies-included-openid-token-enforcement.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: open, id, oauth 2.0, token, enforcement, api gateway, flex gateway, gateway, policy
---

# OpenID Connect OAuth 2.0 Token Enforcement Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OpenID Connect OAuth 2.0 Token Enforcement</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access only to authorized client applications</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/openid-token-enforcement-release-notes">OpenID Connect OAuth 2.0 Token Enforcement</a></p></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Invalid token</p></td></tr><tr><td><p>401 - Unauthorized access or error when connecting to the authorization server</p></td></tr><tr><td><p>403 - Forbidden, invalid client application credentials</p></td></tr><tr><td><p>500 - Bad response from authorization server</p></td></tr></tbody></table>

## Summary

The OpenID Connect Access Token Enforcement policy restricts access to a protected resource to only
those HTTP requests that provide a valid Oauth2 token belonging to a client application with API
access. The policy does not generate tokens but only validates them.

This policy is available only to an organization that is configured to use the OpenID Connect
dynamic client registration as a
[client-management solution](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).

## Use the Policy in Agent Network

Agent Network uses Omni Gateway. The latest policy definition version of the OpenID Connect OAuth
2.0 Token Enforcement policy for Omni Gateway is `0.11.0`. Policy definition versions that start
with `1` are for Mule Gateway and cause an error.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The OpenID Connect Access Token Enforcement policy doesn’t support in Omni Gateway running in Local
Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Scopes</p></div></div></td><td><div><div><p>Displays a space-separated list of supported scopes.</p></div></div></td><td><div><div><p>READ, WRITE, READ and WRITE</p></div></div></td></tr><tr><td><div><div><p>Scope Validation Criteria</p></div></div></td><td><div><div><p>Determines if the token must contain all defined scopes or just one. The values are <strong>Contains all scopes</strong> and <strong>Contains any scope</strong>.</p></div><div><p>For <strong>Contains all scopes</strong>, the policy only accepts tokens with both the <code>READ</code> and <code>WRITE</code> scopes. For <strong>Contains any scopes</strong>, the policy accepts tokens with at least one scope. If no scopes are defined for the <strong>Scopes</strong> parameter, the policy doesn’t validate scopes regardless of what you select for <strong>Scope Validation Criteria</strong>.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>In a proxy scenario, specifies whether headers must be exposed in the request to the backend. User properties returned by the federation server are prefixed with 'X-AGW-' and sent as headers to the backend.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Skip Client Id Validation</p></div></div></td><td><div><div><p>Skips the client application’s API contract validation.</p></div></div></td><td><div><div><p>If selected, Step 4 of the diagram in the <a href="#how-this-policy-works">How This Policy Works</a> section is skipped.</p></div></div></td></tr><tr><td><div><div><p>Authentication request timeout</p></div></div></td><td><div><div><p>Sets the maximum time, in milliseconds, to wait for a response when authenticating with the Access Token validation endpoint.</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr><tr><td><div><div><p>Validated Token TTL</p></div></div></td><td><div><div><p>Sets the maximum time, in seconds, a valid token stays in cache before requiring re-introspection. Use <code>0</code> to disable caching. Use <code>-1</code> to skip this cap and rely solely on the token’s own expiration. The default value is <code>600</code>.</p></div></div></td><td><div><div><p><code>600</code></p></div></div></td></tr><tr><td><div><div><p>Maximum Cache Entries</p></div></div></td><td><div><div><p>Specifies the maximum number of tokens to be stored in the cache. The default value is <code>10000</code>.</p></div></div></td><td><div><div><p><code>10000</code></p></div></div></td></tr><tr><td><div><div><p>Enable Protected Resource Metadata</p></div></div></td><td><div><div><p>Enables <a href="https://www.rfc-editor.org/rfc/rfc9728">RFC 9728</a> OAuth 2.0 Protected Resource Metadata. When enabled, all <code>401</code> responses include a <code>WWW-Authenticate</code> header with the resource metadata URL <code>{api_path}/.well-known/oauth-protected-resource</code>.<br>When a client makes a GET request to this path, Omni Gateway responds with a JSON document containing the authorization server metadata. By default, Omni Gateway derives the authorization server URL supplied in the metadata from the introspection endpoint URL. For example, <code><a href="https://auth.example.com/introspect">https://auth.example.com/introspect</a></code> becomes <code><a href="https://auth.example.com">https://auth.example.com</a></code>.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Override Protected Resource Metadata Authorization Server Url</p></div></div></td><td><div><div><p>Overrides the authorization service URL with a custom URL. For example, when the authorization service uses a different path, such as Keycloak realms.</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Protected Resource Metadata Authorization Server Url</p></div></div></td><td><div><div><p>Server base URL to use when <code>overrideProtectedResourceMetadataAuthorizationServerUrl</code> is enabled.</p></div></div></td><td><div></div></td></tr></tbody></table>

## How This Policy Works

The following diagram illustrates the OpenID Connect Access Token Enforcement policy workflow:

![A flowchart illustrating the process of a user engaging with an API via a PingFederate policy](/mulesoft/current/en-us/gateway/latest/_images/open-id-policy-workflow.png)

As shown in the diagram:

1.  The user first sends an HTTP request to the API protected by the policy.

2.  The policy extracts the token from the request and sends it to the validation endpoint to verify
    the integrity of the token.

3.  The token validation endpoint returns token metadata, including the client ID of the client
    application.

4.  Using a local database updated with contracts previously obtained from Anypoint Platform, the
    policy verifies whether the client ID has access to the API.

5.  If all the validations are successfully completed, the request is allowed to reach the backend.

### Leveraging Token Validation Endpoint Information

When a token validation endpoint successfully validates a token, certain information, such as
configurable fields from OpenID Connect, are returned to the policy.

The following example illustrates the token validation response from the authorization server:

```text
{
    "uid":"john.doe",
    "mail":"john.doe@example.com"
    "token_type":"Bearer",
    "exp": 1516239022
    "alias" : ["Jhon", "Jhonny", "Mr Doe"],
    "address" : {
        "city": "london",
        "road": “abbey road"
    }
}
```

The fields returned by the OAuth provider are processed by the policy, propagated throughout the
flow, and finally exposed to the backend if the application requesting the access uses an HTTP
requester.

### Token Caching in Local Mode

After the system validates a token, that token is cached (by default), until it expires, thereby
improving the performance of the policy. In certain cases, such as in the case of revoked tokens,
you might want to minimize or even disable caching.

The validation endpoint sends multiple properties to the policy, including the expiration time of
the token. If the expiration information is not available, tokens are not cached.

To control the time taken to cache the tokens, before you attempt revalidating against the token
validation endpoint, configure the following parameter in your declarative configuration file:

- policyRef: name: openidconnect-access-token-enforcement-flex config: ...
  maxFederationExpirationTime: <expiration time in seconds>

Setting this property caches the token for the specified amount of time or until the tokens expire,
whichever occurs first. If you have enabled this property and the validation endpoint does not send
the expiration information, tokens are not cached.

To control the number of tokens that can be cached simultaneously, configure the following parameter
in your declarative configuration file.

- policyRef: name: openidconnect-access-token-enforcement-flex config: ... maxCacheSize: <amount of
  tokens to be cached; default value is 1.000; specify 0 to disable caching>

### Token Validation Endpoint Authentication

To complete validating the provided token, the policy sends a request to the validation endpoint.
The policy then obtains the credentials from the client provider configuration in access management,
per the Token Introspection Client section of the OAuth 2.0 Authorization Framework specification.
These credentials are sent in the request body, as specified in the
[Client Authentication section of the OAuth 2.0 Authorization Framework specification](https://tools.ietf.org/html/rfc6749#section-2.3).

Other authentication methods for the token validation endpoint are currently not supported.

## Configuring the Expose Headers Option

If you configured the `Expose Headers` option in the policy and if the application (for example,
out-of-the-box proxies) uses the HTTP requester, the properties are redirected to the backend as
headers.

For each field, the original request to the protected resource is enriched with the HTTP headers
using the format: X-AGW- + <key>=<value>. For the example response from the previous section, the
following headers are added:

```text
X-AGW-uid=john.doe
X-AGW-mail=john.doe@example.com
X-AGW-token_type=Bearer
```

The propagated properties do not include the `scope`, and `exp` objects and arrays.

For further processing within the flow, the original unparsed response from the validation endpoint
is made available. The information is stored in an authentication object.

For example, if a `mail` field is returned to the policy, you can access the value of the field by
using the following DataWeave 2.0 expression:

`#[authentication.properties.userProperties.mail]`

You can obtain the client ID of the OAuth2 token by using the following DataWeave 2.0 expression:

`#[authentication.principal]`

## FAQs

**The OpenID Connect Access Token Enforcement policy does not appear in the list of policies to
apply to the API.**

If the policy does not appear in the policies list, ensure that you have configured the OpenID
client provider in Access Management. For information, see
[Configure OpenID Connect Client Management](https://docs.mulesoft.com/access-management/configure-client-management-openid-task).
If you are using [multiple IdPs](https://docs.mulesoft.com/api-manager/latest/configure-multiple-credential-providers),
verify that the OpenID connect client is properly configured in the API.

**Can I generate OAuth 2.0 tokens with the policy?**

No. The policy only validates the tokens.

**How are the OAuth tokens cached?**

OAuth 2.0 tokens are cached only in memory and are never written to disk.

**Can I configure the Rate-Limiting SLA policy after I configure the OpenID Connect Access Token
Enforcement policy?**

Yes, you can. Apply the Rate-Limiting SLA policy after the OpenID Connect Access Token Enforcement
policy and provide a `Client ID Expression` value using the following DataWeave 2.0 expression:

`#[authentication.principal]`

Because the identity of the requester is already validated by the OpenID Connect Access Token
Enforcement policy, you can leave the `Client Secret Expression` field empty.

<!-- document id=240b411b45b055d49fc010033cb3a6b5eb9eabed11364fa1f6da74f61a7ea8cb url=/mulesoft/current/en-us/gateway/1.12/policies-reorder.md -->

---
product: Omni Gateway
version: 1.12
---

# Ordering Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To execute certain policies before others, configure the order of execution of included and custom
policies.

You can configure both included and custom policies to execute as automated policies, API-level
policies, or upstream-level policies. Automated policies are policies that are applied to all API
instances deployed on the Flex Replica and execute before API-level policies. API-level policies are
inbound policies that are only applied to a specific API instance. Upstream level policies are
outbound policies applied to specific upstreams.

For Flex Gateway running in Connected Mode, use API Manager to order policies. For Flex Gateway
running in Local Mode, use a `PolicyBinding` YAML resource to order policies.

> [!IMPORTANT] You cannot configure the execution order of the
> [Cross-Origin Resource Sharing (CORS) policy](https://docs.mulesoft.com/gateway/1.12/policies-included-cors). The CORS policy executes
> before automated and API-level policies.

## Policy Execution Order

Policies can either execute on the API request, the API response, or both. Policies execute in order
during the API request and in inverse order during the API response. If a policy does not execute in
a certain direction, Flex Gateway skips the policy in that direction. For API requests, policies
execute in the order of automated policies, API-level policies, and outbound policies. The order is
inverted for the response.

For example, if you have policies ordered:

1.  Automated Policy 1

2.  Automated Policy 2

3.  API-Level Policy 1

4.  API-Level Policy 2

5.  Upstream-Level Policy 1

6.  Upstream-Level Policy 2

The policies execute in the following order on the response:

1.  Upstream-Level Policy 2

2.  Upstream-Level Policy 1

3.  API-Level Policy 2

4.  API-Level Policy 1

5.  Automated Policy 2

6.  Automated Policy 1

## Order Automated Policies in Connected Mode

You cannot configure the order of automated policies in API Manager. Automated policies execute in
the order they are applied to the API instance. Apply automated policies in the order you want them
to execute.

## Order Automated Policies in Local Mode

To apply a automated policy to Flex Gateway running in Local Mode, you must apply a resource-level
policy. By doing so, you can apply the same policy to all API instances running on the Flex Replica.

To apply a resource-level policy to all API instances, refer to
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.12/flex-local-secure-api-with-auto-policy).

To order automated resource-level policies, edit the `order` parameter to match when you want the
policy to execute. Ensure that this order does not conflict with the order of any other policies.
For example, if you apply two automated resource-level policies with `order: 1` and `order: 2`, any
API-level policy must start at `order: 3`.

## Order Inbound API-Level Policies for Managed Flex Gateway and Connected Mode

To reorder API-level policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Instances** or **Agent and Tool Instances**, click the name of the API instance whose
    policies you want to reorder.

3.  From the left navigation menu, click **Policies**.

4.  From the top of the list of the applied policies, click **Reorder policies**.

5.  From the **Reorder Applied Policies** section, use the up and down arrows to rearrange the order
    of policies.

6.  Click **Apply order**.

## Order Outbound Policies for Managed Flex Gateway and Connected Mode

To reorder outbound policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Instances** or **Agent and Tool Instances**, click the name of the API instance whose
    policies you want to reorder.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click the more options button (![1%](/mulesoft/current/en-us/gateway/1.12/_images/more-options-menu.png)) of the upstream service
    whose policies you want to reorder.

6.  Use the up and down arrows to rearrange the order of policies.

7.  Click **Apply order**.

## Order Policies in Local Mode

In Flex Gateway running in Local Mode, configure policy ordering via a `PolicyBinding` YAML
resource.

When defining a policy using a `PolicyBinding` YAML resource, edit the `order` parameter to match
when you want the policy to execute. Ensure that you do not assign the same order number to
different policies.

For information about Local Mode policy order, see the
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide#policy-binding).

## Apply Duplicate Policies

Flex Gateway supports applying duplicate policies for all deployment types. Automated, API-level,
Outbound, and resource-level policies all support duplicate policy application.

When applying duplicate policies:

- Add a label to the duplicated policies to differentiate them.

- Consider if it makes sense to apply duplicated policies.

  For example, the duplicated IP allowlist policies allow only IPs that are allowed by both
  policies. Rather than applying duplicated policies, configure the IPs in one policy.

## See Also

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory)

<!-- document id=a9ed99e0fae0652ca53b08bd3fb0d233c8eee46a555070ed2c54397c8bd2705d url=/mulesoft/current/en-us/gateway/1.13/policies-reorder.md -->

---
product: Omni Gateway
version: 1.13
---

# Ordering Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To execute certain policies before others, configure the order of execution of included and custom
policies.

You can configure both included and custom policies to execute as automated policies, API-level
policies, or upstream-level policies. Automated policies are policies that are applied to all API
instances deployed on the Omni Replica and execute before API-level policies. API-level policies are
inbound policies that are only applied to a specific API instance. Upstream level policies are
outbound policies applied to specific upstreams.

For Omni Gateway running in Connected Mode, use API Manager to order policies. For Omni Gateway
running in Local Mode, use a `PolicyBinding` YAML resource to order policies.

> [!IMPORTANT] You cannot configure the execution order of the
> [Cross-Origin Resource Sharing (CORS) policy](https://docs.mulesoft.com/gateway/1.13/policies-included-cors). The CORS policy executes
> before automated and API-level policies.

## Policy Execution Order

Policies can either execute on the API request, the API response, or both. Policies execute in order
during the API request and in inverse order during the API response. If a policy does not execute in
a certain direction, Omni Gateway skips the policy in that direction. For API requests, policies
execute in the order of automated policies, API-level policies, and outbound policies. The order is
inverted for the response.

For example, if you have policies ordered:

1.  Automated Policy 1

2.  Automated Policy 2

3.  API-Level Policy 1

4.  API-Level Policy 2

5.  Upstream-Level Policy 1

6.  Upstream-Level Policy 2

The policies execute in the following order on the response:

1.  Upstream-Level Policy 2

2.  Upstream-Level Policy 1

3.  API-Level Policy 2

4.  API-Level Policy 1

5.  Automated Policy 2

6.  Automated Policy 1

## Order Automated Policies in Connected Mode

You cannot configure the order of automated policies in API Manager. Automated policies execute in
the order they are applied to the API instance. Apply automated policies in the order you want them
to execute.

## Order Automated Policies in Local Mode

To apply a automated policy to Omni Gateway running in Local Mode, you must apply a resource-level
policy. By doing so, you can apply the same policy to all API instances running on the Omni Replica.

To apply a resource-level policy to all API instances, refer to
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.13/local-secure-api-with-auto-policy).

To order automated resource-level policies, edit the `order` parameter to match when you want the
policy to execute. Ensure that this order does not conflict with the order of any other policies.
For example, if you apply two automated resource-level policies with `order: 1` and `order: 2`, any
API-level policy must start at `order: 3`.

## Order Inbound API-Level Policies for Managed Omni Gateway and Connected Mode

To reorder API-level policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Instances** or **Agent and Tool Instances**, click the name of the API instance whose
    policies you want to reorder.

3.  From the left navigation menu, click **Policies**.

4.  From the top of the list of the applied policies, click **Reorder policies**.

5.  From the **Reorder Applied Policies** section, use the up and down arrows to rearrange the order
    of policies.

6.  Click **Apply order**.

## Order Outbound Policies for Managed Omni Gateway and Connected Mode

To reorder outbound policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Instances** or **Agent and Tool Instances**, click the name of the API instance whose
    policies you want to reorder.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click the more options button (![1%](/mulesoft/current/en-us/gateway/1.13/_images/more-options-menu.png)) of the upstream service
    whose policies you want to reorder.

6.  Use the up and down arrows to rearrange the order of policies.

7.  Click **Apply order**.

## Order Policies in Local Mode

In Omni Gateway running in Local Mode, configure policy ordering via a `PolicyBinding` YAML
resource.

When defining a policy using a `PolicyBinding` YAML resource, edit the `order` parameter to match
when you want the policy to execute. Ensure that you do not assign the same order number to
different policies.

For information about Local Mode policy order, see the
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide#policy-binding).

## Apply Duplicate Policies

Omni Gateway supports applying duplicate policies for all deployment types. Automated, API-level,
Outbound, and resource-level policies all support duplicate policy application.

When applying duplicate policies:

- Add a label to the duplicated policies to differentiate them.

- Consider if it makes sense to apply duplicated policies.

  For example, the duplicated IP allowlist policies allow only IPs that are allowed by both
  policies. Rather than applying duplicated policies, configure the IPs in one policy.

## See Also

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

<!-- document id=e70f91abd8380643538454a5ac3d1003c4c3474ee4ba9ffe284d9aafe23535d9 url=/mulesoft/current/en-us/gateway/1.9/policies-reorder.md -->

---
product: Omni Gateway
version: 1.9
---

# Ordering Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To execute certain policies before others, configure the order of execution of included and custom
policies.

You can configure both included and custom policies to execute as automated policies, API-level
policies, or upstream-level policies. Automated policies are policies that are applied to all API
instances deployed on the Flex Replica and execute before API-level policies. API-level policies are
inbound policies that are only applied to a specific API instance. Upstream level policies are
outbound policies applied to specific upstreams.

For Flex Gateway running in Connected Mode, use API Manager to order policies. For Flex Gateway
running in Local Mode, use a `PolicyBinding` YAML resource to order policies.

> [!IMPORTANT] You cannot configure the execution order of the
> [Cross-Origin Resource Sharing (CORS) policy](https://docs.mulesoft.com/gateway/1.9/policies-included-cors). The CORS policy executes
> before automated and API-level policies.

## Policy Execution Order

Policies can either execute on the API request, the API response, or both. Policies execute in order
during the API request and in inverse order during the API response. If a policy does not execute in
a certain direction, Flex Gateway skips the policy in that direction. For API requests, policies
execute in the order of automated policies, API-level policies, and outbound policies. The order is
inverted for the response.

For example, if you have policies ordered:

1.  Automated Policy 1

2.  Automated Policy 2

3.  API-Level Policy 1

4.  API-Level Policy 2

5.  Upstream-Level Policy 1

6.  Upstream-Level Policy 2

The policies execute in the following order on the response:

1.  Upstream-Level Policy 2

2.  Upstream-Level Policy 1

3.  API-Level Policy 2

4.  API-Level Policy 1

5.  Automated Policy 2

6.  Automated Policy 1

## Order Automated Policies in Connected Mode

You cannot configure the order of automated policies in API Manager. Automated policies execute in
the order they are applied to the API instance. Apply automated policies in the order you want them
to execute.

## Order Automated Policies in Local Mode

To apply a automated policy to Flex Gateway running in Local Mode, you must apply a resource-level
policy. By doing so, you can apply the same policy to all API instances running on the Flex Replica.

To apply a resource-level policy to all API instances, refer to
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.9/flex-local-secure-api-with-auto-policy).

To order automated resource-level policies, edit the `order` parameter to match when you want the
policy to execute. Ensure that this order does not conflict with the order of any other policies.
For example, if you apply two automated resource-level policies with `order: 1` and `order: 2`, any
API-level policy must start at `order: 3`.

## Order Inbound API-Level Policies for Managed Flex Gateway and Connected Mode

To reorder API-level policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Administration**, click the name of the API instance whose policies you want to
    reorder.

3.  From the left navigation menu, click **Policies**.

4.  From the top of the list of the applied policies, click **Reorder policies**.

5.  From the **Reorder Applied Policies** section, use the up and down arrows to rearrange the order
    of policies.

6.  Click **Apply order**.

## Order Outbound Policies for Managed Flex Gateway and Connected Mode

To reorder outbound policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Administration**, click the name of the API instance whose policies you want to
    reorder.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click the more options button (![1%](/mulesoft/current/en-us/gateway/1.9/_images/more-options-menu.png)) of the upstream service
    whose policies you want to reorder.

6.  Use the up and down arrows to rearrange the order of policies.

7.  Click **Apply order**.

## Order Policies in Local Mode

In Flex Gateway running in Local Mode, configure policy ordering via a `PolicyBinding` YAML
resource.

When defining a policy using a `PolicyBinding` YAML resource, edit the `order` parameter to match
when you want the policy to execute. Ensure that you do not assign the same order number to
different policies.

For information about Local Mode policy order, see the
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide#policy-binding).

## See Also

- [Included Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory)

<!-- document id=525eb657824d4b5ca1c7103233332fd103c43306b7ab1a26a5160dd4d47a08e6 url=/mulesoft/current/en-us/gateway/latest/policies-reorder.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Ordering Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To execute certain policies before others, configure the order of execution of included and custom
policies.

You can configure both included and custom policies to execute as automated policies, API-level
policies, or upstream-level policies. Automated policies are policies that are applied to all API
instances deployed on the Omni Replica and execute before API-level policies. API-level policies are
inbound policies that are only applied to a specific API instance. Upstream level policies are
outbound policies applied to specific upstreams.

For Omni Gateway running in Connected Mode, use API Manager to order policies. For Omni Gateway
running in Local Mode, use a `PolicyBinding` YAML resource to order policies.

> [!IMPORTANT] You cannot configure the execution order of the
> [Cross-Origin Resource Sharing (CORS) policy](https://docs.mulesoft.com/gateway/latest/policies-included-cors). The CORS policy executes
> before automated and API-level policies.

## Policy Execution Order

Policies can either execute on the API request, the API response, or both. Policies execute in order
during the API request and in inverse order during the API response. If a policy does not execute in
a certain direction, Omni Gateway skips the policy in that direction. For API requests, policies
execute in the order of automated policies, API-level policies, and outbound policies. The order is
inverted for the response.

For example, if you have policies ordered:

1.  Automated Policy 1

2.  Automated Policy 2

3.  API-Level Policy 1

4.  API-Level Policy 2

5.  Upstream-Level Policy 1

6.  Upstream-Level Policy 2

The policies execute in the following order on the response:

1.  Upstream-Level Policy 2

2.  Upstream-Level Policy 1

3.  API-Level Policy 2

4.  API-Level Policy 1

5.  Automated Policy 2

6.  Automated Policy 1

## Order Automated Policies in Connected Mode

You cannot configure the order of automated policies in API Manager. Automated policies execute in
the order they are applied to the API instance. Apply automated policies in the order you want them
to execute.

## Order Automated Policies in Local Mode

To apply a automated policy to Omni Gateway running in Local Mode, you must apply a resource-level
policy. By doing so, you can apply the same policy to all API instances running on the Omni Replica.

To apply a resource-level policy to all API instances, refer to
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/latest/local-secure-api-with-auto-policy).

To order automated resource-level policies, edit the `order` parameter to match when you want the
policy to execute. Ensure that this order does not conflict with the order of any other policies.
For example, if you apply two automated resource-level policies with `order: 1` and `order: 2`, any
API-level policy must start at `order: 3`.

## Order Inbound API-Level Policies for Managed Omni Gateway and Connected Mode

To reorder API-level policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Instances** or **Agent and Tool Instances**, click the name of the API instance whose
    policies you want to reorder.

3.  From the left navigation menu, click **Policies**.

4.  From the top of the list of the applied policies, click **Reorder policies**.

5.  From the **Reorder Applied Policies** section, use the up and down arrows to rearrange the order
    of policies.

6.  Click **Apply order**.

## Order Outbound Policies for Managed Omni Gateway and Connected Mode

To reorder outbound policies:

1.  Go to **Anypoint Platform > API Manager**.

2.  In **API Instances** or **Agent and Tool Instances**, click the name of the API instance whose
    policies you want to reorder.

3.  From the side navigation panel, click **Policies**.

4.  Click the **Outbound policies** tab.

5.  Click the more options button (![1%](/mulesoft/current/en-us/gateway/latest/_images/more-options-menu.png)) of the upstream service
    whose policies you want to reorder.

6.  Use the up and down arrows to rearrange the order of policies.

7.  Click **Apply order**.

## Order Policies in Local Mode

In Omni Gateway running in Local Mode, configure policy ordering via a `PolicyBinding` YAML
resource.

When defining a policy using a `PolicyBinding` YAML resource, edit the `order` parameter to match
when you want the policy to execute. Ensure that you do not assign the same order number to
different policies.

For information about Local Mode policy order, see the
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide#policy-binding).

## Apply Duplicate Policies

Omni Gateway supports applying duplicate policies for all deployment types. Automated, API-level,
Outbound, and resource-level policies all support duplicate policy application.

When applying duplicate policies:

- Add a label to the duplicated policies to differentiate them.

- Consider if it makes sense to apply duplicated policies.

  For example, the duplicated IP allowlist policies allow only IPs that are allowed by both
  policies. Rather than applying duplicated policies, configure the IPs in one policy.

## See Also

- [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

<!-- document id=2d790a797e55784e29815453aacbf304e417aeae2c5ebfd343a9e5b0be2422c7 url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-message-logging.md -->

# Outbound Message Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Outbound Message Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Flex Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.11.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The Outbound Message Logging policy logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service. This policy is applied at the upstream level.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1beta1
kind: PolicyBinding
metadata:
  name: outbound-message-logging
spec:
  targetRef:
    kind: Service
    name: upstream
  policyRef:
    name: message-logging-outbound-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of configurations.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.message</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to the message log. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.conditional</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to whether the message should be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.category</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Default category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Log message prefix that indicates the package and class where the log is executed.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.level</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code><br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.firstSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged before the outbound request is sent to the upstream service, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.secondSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged after receiving the response from the upstream service, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

apiVersion: gateway.mulesoft.com/v1beta1
kind: PolicyBinding
metadata:
  name: outbound-message-logging
spec:
  targetRef:
    kind: Service
    name: my-upstream
  policyRef:
    name: message-logging-outbound-flex
  config:
    loggingConfiguration:
      - itemName: "Outbound Request Log"
        itemData:
          message: "#\[payload\]"
          conditional: "#\[attributes.queryParams\['debug'\]=='true'\]"
          level: "INFO"
          firstSection: true
      - itemName: "Outbound Response Log"
        itemData:
          message: "#\['Upstream response: ' ++ attributes.statusCode as String\]"
          level: "INFO"
          secondSection: true

### [](#connected-mode)Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave expression for extracting the message to be logged from outbound requests or upstream responses. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Conditional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave Boolean expression used to specify whether a message is to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Category</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A prefix in the log message that indicates the package and class where the log is executed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Level</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code>.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Before Sending Request</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages before the outbound request is sent to the upstream service, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">After Receiving Response</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages after receiving the response from the upstream service, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

## [](#dataweave-support)DataWeave Expressions Support

The Outbound Message Logging policy supports the [standard DataWeave Expressions supported by Flex Gateway policies](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support) and the following additional [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) DataWeave expressions. Format the following expressions `[vars.<expressions>]`, for example `[vars.orgId]`:

- `orgId`
- `masterOrgId`
- `envId`
- `apiId`
- `apiName`
- `apiInstanceName`
- `apiVersion`
- `receivedTs` (rfc3339)
- `repliedTs` (rfc3339, only available in response context)
- `runtimeVersion` (For example: `v1.7.0`)
- `hostId` (For example: `my-host`)
- `reqId` (Referred to as `traceId` in Flex Gateway logs)
- `requestDisposition` (`PROCESSED` or `VIOLATION`, only available in request context)
- `request.remoteAddress`
- `request.method`
- `request.requestPath`
- `request.headers` (all request headers)
- `upstream.uri` (URI of the upstream service)
- `upstream.headers` (headers sent to upstream service)
- `upstream.statusCode` (status code from upstream response, only available in response context)
- `violation.clientId` (Only available in response context)
- `violation.clientName` (Only available in response context)
- `violation.policyName` (Only available in response context)
- `violation.violationType` (`VIOLATION` or `ERROR`, only available in response context)

## [](#how-this-policy-works)How This Policy Works

Logging an outbound policy consists of the following sequence:

1. An outbound request is prepared to be sent to an upstream service.
2. The message is logged if these conditions are `true`:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy is not set, or is set and the condition is met.
    - The `firstSection` flag is enabled (if logging before sending the request).
3. The request is sent to the upstream service.
4. The upstream service responds.
5. The message is logged if these conditions are `true`:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy is not set, or is set and the condition is met.
    - The `secondSection` flag is enabled (if logging after receiving the response).
6. The response is returned to the client. Outbound Message Logging Policy does not interfere with the execution of any policy nor its flow.
7. The message appears in the application log.

## [](#logging-format)Logging Format

A message log uses this format:

`<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>`

- `policy-name`: displays the name of the policy binding.
- `api-name`: displays the name of the api instance.
- `request uuid`: displays a unique identifier for the request that triggered the message.

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=f6b1eac0923b722ad616a5533035dae50f2763bc952f264b582fc5068d478262 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-message-logging.md -->

# Outbound Message Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Outbound Message Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.11.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-message-logging-release-notes" class="xref page">Outbound Message Logging</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The Outbound Message Logging policy logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service. This policy is applied at the upstream level.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1beta1
kind: PolicyBinding
metadata:
  name: outbound-message-logging
spec:
  targetRef:
    kind: Service
    name: upstream
  policyRef:
    name: message-logging-outbound-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of configurations.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.message</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to the message log. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.conditional</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to whether the message should be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.category</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Default category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Log message prefix that indicates the package and class where the log is executed.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.level</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code><br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.firstSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged before the outbound request is sent to the upstream service, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.secondSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged after receiving the response from the upstream service, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

apiVersion: gateway.mulesoft.com/v1beta1
kind: PolicyBinding
metadata:
  name: outbound-message-logging
spec:
  targetRef:
    kind: Service
    name: my-upstream
  policyRef:
    name: message-logging-outbound-flex
  config:
    loggingConfiguration:
      - itemName: "Outbound Request Log"
        itemData:
          message: "#\[payload\]"
          conditional: "#\[attributes.queryParams\['debug'\]=='true'\]"
          level: "INFO"
          firstSection: true
      - itemName: "Outbound Response Log"
        itemData:
          message: "#\['Upstream response: ' ++ attributes.statusCode as String\]"
          level: "INFO"
          secondSection: true

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave expression for extracting the message to be logged from outbound requests or upstream responses. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Conditional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave Boolean expression used to specify whether a message is to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Category</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A prefix in the log message that indicates the package and class where the log is executed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Level</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code>.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Before Sending Request</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages before the outbound request is sent to the upstream service, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">After Receiving Response</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages after receiving the response from the upstream service, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

## [](#dataweave-support)DataWeave Expressions Support

The Outbound Message Logging policy supports the [standard DataWeave Expressions supported by Omni Gateway policies](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support) and the following additional [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) DataWeave expressions. Format the following expressions `[vars.<expressions>]`, for example `[vars.orgId]`:

- `orgId`
- `masterOrgId`
- `envId`
- `apiId`
- `apiName`
- `apiInstanceName`
- `apiVersion`
- `receivedTs` (rfc3339)
- `repliedTs` (rfc3339, only available in response context)
- `runtimeVersion` (For example: `v1.7.0`)
- `hostId` (For example: `my-host`)
- `reqId` (Referred to as `traceId` in Omni Gateway logs)
- `requestDisposition` (`PROCESSED` or `VIOLATION`, only available in request context)
- `request.remoteAddress`
- `request.method`
- `request.requestPath`
- `request.headers` (all request headers)
- `upstream.uri` (URI of the upstream service)
- `upstream.headers` (headers sent to upstream service)
- `upstream.statusCode` (status code from upstream response, only available in response context)
- `violation.clientId` (Only available in response context)
- `violation.clientName` (Only available in response context)
- `violation.policyName` (Only available in response context)
- `violation.violationType` (`VIOLATION` or `ERROR`, only available in response context)

## [](#how-this-policy-works)How This Policy Works

Logging an outbound policy consists of the following sequence:

1. An outbound request is prepared to be sent to an upstream service.
2. The message is logged if these conditions are `true`:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy is not set, or is set and the condition is met.
    - The `firstSection` flag is enabled (if logging before sending the request).
3. The request is sent to the upstream service.
4. The upstream service responds.
5. The message is logged if these conditions are `true`:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy is not set, or is set and the condition is met.
    - The `secondSection` flag is enabled (if logging after receiving the response).
6. The response is returned to the client. Outbound Message Logging Policy does not interfere with the execution of any policy nor its flow.
7. The message appears in the application log.

## [](#logging-format)Logging Format

A message log uses this format:

`<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>`

- `policy-name`: displays the name of the policy binding.
- `api-name`: displays the name of the api instance.
- `request uuid`: displays a unique identifier for the request that triggered the message.

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=4c973e539fdc1043e62ad0c6a4a3fbccb9656be67b67dffa427960a3b3737aaf url=/mulesoft/current/en-us/gateway/latest/policies-outbound-message-logging.md -->

# Outbound Message Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Outbound Message Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Troubleshooting</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.11.0</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-message-logging-release-notes" class="xref page">Outbound Message Logging</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-middle"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The Outbound Message Logging policy logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service. This policy is applied at the upstream level.

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#local-mode)Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1beta1
kind: PolicyBinding
metadata:
  name: outbound-message-logging
spec:
  targetRef:
    kind: Service
    name: upstream
  policyRef:
    name: message-logging-outbound-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL
    enableDataMasking: <bool> // OPTIONAL
    dataMasking: // OPTIONAL
      entities:
        - <string> // Supported values: Email, US SSN, Credit Card, Phone Number
      customPatterns:
        - name: <string>
          pattern: <string>

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
<th class="tableblock halign-left valign-top">Default Value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Array of configurations.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemName</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Configuration name.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.message</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to the message log. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.conditional</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>true</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression that resolves to whether the message should be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.category</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Default category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Log message prefix that indicates the package and class where the log is executed.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.level</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Required</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>N/A</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code><br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.firstSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged before the outbound request is sent to the upstream service, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>loggingConfiguration.itemData.secondSection</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Boolean that indicates if messages are logged after receiving the response from the upstream service, taking into account the order in which this policy is applied.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>enableDataMasking</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>false</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>When enabled, the policy detects and masks configured PII in log messages before they are written. Request and response bodies are forwarded to the upstream service unchanged.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>dataMasking.entities</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>[]</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of built-in PII types to mask. Supported values: <code>Email</code>, <code>US SSN</code>, <code>Credit Card</code>, and <code>Phone Number</code>.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>dataMasking.customPatterns</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Optional</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>[]</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of custom patterns to mask when built-in PII detection doesn’t cover the value. Each pattern must have a <code>name</code> and a <code>pattern</code> (regular expression) property.</p>
</div></div></td>
</tr>
</tbody>
</table>

#### [](#resource-configuration-example)Resource Configuration Example

apiVersion: gateway.mulesoft.com/v1beta1
kind: PolicyBinding
metadata:
  name: outbound-message-logging
spec:
  targetRef:
    kind: Service
    name: my-upstream
  policyRef:
    name: message-logging-outbound-flex
  config:
    loggingConfiguration:
      - itemName: "Outbound Request Log"
        itemData:
          message: "#\[payload\]"
          conditional: "#\[attributes.queryParams\['debug'\]=='true'\]"
          level: "INFO"
          firstSection: true
      - itemName: "Outbound Response Log"
        itemData:
          message: "#\['Upstream response: ' ++ attributes.statusCode as String\]"
          level: "INFO"
          secondSection: true

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required or Optional</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Message</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave expression for extracting the message to be logged from outbound requests or upstream responses. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Conditional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A DataWeave Boolean expression used to specify whether a message is to be logged. To learn more about supported DataWeave expressions, see <a href="#dataweave-support">DataWeave Expressions Support</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Category</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A prefix in the log message that indicates the package and class where the log is executed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Level</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code>.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Required</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Before Sending Request</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages before the outbound request is sent to the upstream service, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">After Receiving Response</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to cause your logging policy to log messages after receiving the response from the upstream service, taking into account the order in which this policy is applied.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enable data masking</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detect and mask configured PII before writing log messages. Request and response bodies are forwarded to the upstream service unchanged.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">PII Detection</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Select built-in PII types to mask: Email, US SSN, Credit Card, and Phone Number.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Custom Patterns</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Add a regular expression pattern to mask a value that built-in PII detection doesn’t cover. Each pattern has a name and a regex.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional</p></td>
</tr>
</tbody>
</table>

## [](#dataweave-support)DataWeave Expressions Support

The Outbound Message Logging policy supports the [standard DataWeave Expressions supported by Omni Gateway policies](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support) and the following additional [`vars`](https://docs.mulesoft.com/dataweave/latest/dataweave-variables-context) DataWeave expressions. Format the following expressions `[vars.<expressions>]`, for example `[vars.orgId]`:

- `orgId`
- `masterOrgId`
- `envId`
- `apiId`
- `apiName`
- `apiInstanceName`
- `apiVersion`
- `receivedTs` (rfc3339)
- `repliedTs` (rfc3339, only available in response context)
- `runtimeVersion` (For example: `v1.7.0`)
- `hostId` (For example: `my-host`)
- `reqId` (Referred to as `traceId` in Omni Gateway logs)
- `requestDisposition` (`PROCESSED` or `VIOLATION`, only available in request context)
- `request.remoteAddress`
- `request.method`
- `request.requestPath`
- `request.headers` (all request headers)
- `upstream.uri` (URI of the upstream service)
- `upstream.headers` (headers sent to upstream service)
- `upstream.statusCode` (status code from upstream response, only available in response context)
- `violation.clientId` (Only available in response context)
- `violation.clientName` (Only available in response context)
- `violation.policyName` (Only available in response context)
- `violation.violationType` (`VIOLATION` or `ERROR`, only available in response context)

## [](#how-this-policy-works)How This Policy Works

Logging an outbound policy consists of the following sequence:

1. An outbound request is prepared to be sent to an upstream service.
2. The message is logged if these conditions are `true`:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy is not set, or is set and the condition is met.
    - The `firstSection` flag is enabled (if logging before sending the request).
3. The request is sent to the upstream service.
4. The upstream service responds.
5. The message is logged if these conditions are `true`:
    
    - The level and category of the log defined in the policy are included in the logger defined in the configuration file.
    - Either the conditional field of the policy is not set, or is set and the condition is met.
    - The `secondSection` flag is enabled (if logging after receiving the response).
6. The response is returned to the client. Outbound Message Logging Policy does not interfere with the execution of any policy nor its flow.
7. The message appears in the application log.

## [](#logging-format)Logging Format

A message log uses this format:

`<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>`

- `policy-name`: displays the name of the policy binding.
- `api-name`: displays the name of the api instance.
- `request uuid`: displays a unique identifier for the request that triggered the message.

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=a0cfc365ad07896d10860a6a3b434a89ac3220ee2acc9ffe1bea6170ae352eef url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-directory.md -->

---
product: Omni Gateway
version: 1.12
---

# Outbound Policies Directory

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## Outbound Policies Included in Flex Gateway

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Policy</th><th>Category</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-a2a-intask-authorization-code">A2A In-Task Authorization Code</a></p></td><td><p>A2A</p></td><td><p>Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-aws-lambda">AWS lambda</a></p></td><td><p>Transformation</p></td><td><p>Triggers an AWS Lambda function from a standard HTTP request</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-aws-signature">AWS Request Signature</a></p></td><td><p>Security</p></td><td><p>Signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A)</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-circuit-breaker">Circuit Breaker</a></p></td><td><p>Quality of Service</p></td><td><p>Prevents an upstream from receiving too many requests or connections</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-basic-auth">Credential Injection Basic Authentication</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-api-key">Credential Injection API Key</a></p></td><td><p>Security</p></td><td><p>Injects an API key or client credentials headers into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-oauth">Credential Injection OAuth 2.0</a></p></td><td><p>Security</p></td><td><p>Injects an OAuth 2.0 authorization header into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-jwt-generation">Credential Injection JWT Generation</a></p></td><td><p>Security</p></td><td><p>Generates and injects a JWT token into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-oauth-obo">OAuth 2.0 OBO Credential Injection</a></p></td><td><p>Security</p></td><td><p>Exchanges incoming bearer tokens using OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of, or OAuth 2.0 Token Exchange with CIBA</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-message-logging">Outbound Message Logging</a></p></td><td><p>Troubleshooting</p></td><td><p>Logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound">Transport Layer Security (TLS) - Outbound</a></p></td><td><p>Security</p></td><td><p>Enables two-way authentication between the API proxy and an upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.12/policies-outbound-upstream-idle-timeout">Upstream Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Sets the maximum idle duration for a stream between Flex Gateway and an upstream service</p></td></tr></tbody></table>

## See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=4244dea82c4b61a78b0e10f362c632ba2d1838fd706429f0b247347db188ce59 url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-directory.md -->

---
product: Omni Gateway
version: 1.13
---

# Outbound Policies Directory

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## Outbound Policies Included in Omni Gateway

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Policy</th><th>Category</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-a2a-intask-authorization-code">A2A In-Task Authorization Code</a></p></td><td><p>A2A</p></td><td><p>Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-a2a-v1-to-v03-transcoder">A2A v1 to v0.3 Transcoder</a></p></td><td><p>A2A</p></td><td><p>Transcodes protocol messages bidirectionally between A2A v1.0 JSON-RPC clients and A2A v0.3 upstream servers</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-aws-lambda">AWS lambda</a></p></td><td><p>Transformation</p></td><td><p>Triggers an AWS Lambda function from a standard HTTP request</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-aws-signature">AWS Request Signature</a></p></td><td><p>Security</p></td><td><p>Signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A)</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-circuit-breaker">Circuit Breaker</a></p></td><td><p>Quality of Service</p></td><td><p>Prevents an upstream from receiving too many requests or connections</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-basic-auth">Credential Injection Basic Authentication</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-api-key">Credential Injection API Key</a></p></td><td><p>Security</p></td><td><p>Injects an API key or client credentials headers into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-oauth">Credential Injection OAuth 2.0</a></p></td><td><p>Security</p></td><td><p>Injects an OAuth 2.0 authorization header into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-jwt-generation">Credential Injection JWT Generation</a></p></td><td><p>Security</p></td><td><p>Generates and injects a JWT token into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-oauth-obo">OAuth 2.0 OBO Credential Injection</a></p></td><td><p>Security</p></td><td><p>Exchanges incoming bearer tokens using OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of, or OAuth 2.0 Token Exchange with CIBA</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-message-logging">Outbound Message Logging</a></p></td><td><p>Troubleshooting</p></td><td><p>Logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound">Transport Layer Security (TLS) - Outbound</a></p></td><td><p>Security</p></td><td><p>Enables two-way authentication between the API proxy and an upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.13/policies-outbound-upstream-idle-timeout">Upstream Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Sets the maximum idle duration for a stream between Omni Gateway and an upstream service</p></td></tr></tbody></table>

## See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=f0f86242e5b90999a4fd51d13bbb8c9dd39f31486e6037eb0d6424c5f1ca9c28 url=/mulesoft/current/en-us/gateway/1.9/policies-outbound-directory.md -->

---
product: Omni Gateway
version: 1.9
---

# Outbound Policies Directory

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## Outbound Policies Included in Flex Gateway

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Policy</th><th>Category</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-outbound-aws-lambda">AWS lambda</a></p></td><td><p>Transformation</p></td><td><p>Triggers an AWS Lambda function from a standard HTTP request</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-outbound-circuit-breaker">Circuit Breaker</a></p></td><td><p>Quality of Service</p></td><td><p>Prevents an upstream from receiving too many requests or connections</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-outbound-basic-auth">Credential Injection Basic Authentication</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-outbound-oauth">Credential Injection OAuth 2.0</a></p></td><td><p>Security</p></td><td><p>Adds headers to a request or a response</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/1.9/policies-outbound-upstream-idle-timeout">Upstream Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Sets the maximum idle duration for a stream between Flex Gateway and an upstream service</p></td></tr></tbody></table>

## See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=469f8aa8e051bbeae1484e9c9b997121be3cad3ddb5e85b85c0f59ec8fc14ed8 url=/mulesoft/current/en-us/gateway/latest/policies-outbound-directory.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Outbound Policies Directory

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## Outbound Policies Included in Omni Gateway

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Policy</th><th>Category</th><th>Summary</th></tr></thead><tbody><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-a2a-intask-authorization-code">A2A In-Task Authorization Code</a></p></td><td><p>A2A</p></td><td><p>Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-a2a-v1-to-v03-transcoder">A2A v1 to v0.3 Transcoder</a></p></td><td><p>A2A</p></td><td><p>Transcodes protocol messages bidirectionally between A2A v1.0 JSON-RPC clients and A2A v0.3 upstream servers</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-aws-lambda">AWS lambda</a></p></td><td><p>Transformation</p></td><td><p>Triggers an AWS Lambda function from a standard HTTP request</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-aws-signature">AWS Request Signature</a></p></td><td><p>Security</p></td><td><p>Signs outgoing requests with AWS Signature Version 4 (SigV4) or Signature Version 4A (SigV4A)</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-circuit-breaker">Circuit Breaker</a></p></td><td><p>Quality of Service</p></td><td><p>Prevents an upstream from receiving too many requests or connections</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-basic-auth">Credential Injection Basic Authentication</a></p></td><td><p>Security</p></td><td><p>Allows access based on the basic authorization mechanism, with a single user-password</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-api-key">Credential Injection API Key</a></p></td><td><p>Security</p></td><td><p>Injects an API key or client credentials headers into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-oauth">Credential Injection OAuth 2.0</a></p></td><td><p>Security</p></td><td><p>Injects an OAuth 2.0 authorization header into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-jwt-generation">Credential Injection JWT Generation</a></p></td><td><p>Security</p></td><td><p>Generates and injects a JWT token into outgoing requests</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-oauth-obo">OAuth 2.0 OBO Credential Injection</a></p></td><td><p>Security</p></td><td><p>Exchanges incoming bearer tokens using OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of, or OAuth 2.0 Token Exchange with CIBA</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-message-logging">Outbound Message Logging</a></p></td><td><p>Troubleshooting</p></td><td><p>Logs custom messages from outbound requests sent to upstream services, responses from upstream services, or information from other outbound policies applied to the same upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound">Transport Layer Security (TLS) - Outbound</a></p></td><td><p>Security</p></td><td><p>Enables two-way authentication between the API proxy and an upstream service</p></td></tr><tr><td><p><a href="https://docs.mulesoft.com/gateway/latest/policies-outbound-upstream-idle-timeout">Upstream Idle Timeout</a></p></td><td><p>Quality of Service</p></td><td><p>Sets the maximum idle duration for a stream between Omni Gateway and an upstream service</p></td></tr></tbody></table>

## See Also

- [Policy Availability by Gateway](https://docs.mulesoft.com/gateway-home/#policy-availability-by-gateway)

<!-- document id=d4e2f267b1424a63278238bbc8cd7b79fa98be25eac9fec87ed15e86212503b0 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-k8-external-dns.md -->

---
product: Omni Gateway
version: 1.12
---

# Provide a Domain Name for an Application on Your Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain name
instead of a difficult-to-understand external IP or random host name.

[ExternalDNS](https://github.com/kubernetes-sigs/external-dns/blob/master/README.md) is an open
source project that supports DNS configurations on many DNS providers. The tool is _not_ a DNS
server or provider. Instead, ExternalDNS discovers Kubernetes resources through public DNS servers
and configures the resources for supported DNS providers.

This guide uses ExternalDNS to configure domain names in an AWS Route 53 provider, which is one of
the stable providers supported by ExternalDNS.

## Before You Begin

Ensure that the following prerequisites are in place:

- A Kubernetes cluster on AWS

- A Flex Gateway deployment to an AWS cluster or a registered Flex Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up) or
  [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-getting-started).

- An AWS Identity and Access Management (IAM) policy that allows ExternalDNS to update Amazon Route
  53 Resource Record Sets and Hosted Zones

  To use another target or create the IAM Policy with these permissions, see the
  [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/aws.md).

## Add ExternalDNS to Your Cluster

Add ExternalDNS (`external-dns`) to your cluster by creating and deploying a YAML configuration file
with the following content to your cluster:

1.  Create a YAML file with the following settings.

    ```yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: external-dns
      labels:
        app.kubernetes.io/name: external-dns
    spec:
      strategy:
        type: Recreate
      selector:
        matchLabels:
          app.kubernetes.io/name: external-dns
      template:
        metadata:
          labels:
            app.kubernetes.io/name: external-dns
        spec:
          containers:
            - name: external-dns
              image: registry.k8s.io/external-dns/external-dns:v0.13.1
              args:
                - --source=service
                - --source=ingress
                - --domain-filter=<your-domain> # makes only hosted zones visible
                - --provider=aws
                - --policy=upsert-only # prevents record deletion
                - --aws-zone-type=public # public zones only
                - --registry=txt
                - --txt-owner-id=my-hostedzone-identifier
              env:
                - name: AWS_DEFAULT_REGION
                  value: <aws-region> # sets the EKS region
          # # Uncomment the following settings when using static credentials
          #       - name: AWS_SHARED_CREDENTIALS_FILE
          #        value: /.aws/credentials
          #     volumeMounts:
          #       - name: aws-credentials
          #         mountPath: /.aws
          #         readOnly: true
          # volumes:
          #   - name: aws-credentials
          #     secret:
          #       secretName: external-dns
    ```

2.  In your new YAML file, set the following options, as needed, for your deployment:

    - `args` options:

      - `- --domain-filter=<your-domain>`: Make hosted zones that match your domain visible to
        ExternalDNS. Omit this option to process all available hosted zones.

        The option is critical for making `external-dns` work as intended.

      - `- --policy=upsert-only`: Prevent ExternalDNS from deleting any records. Omit this option to
        enable full synchronization.

      - `- --aws-zone-type=public`: Make only public hosted zones visible. Valid values are
        `public`, `private`, or no value for both types of zones.

    - `env` option `value: <aws-region>`: Set the region in which your EKS cluster is installed, for
      example, `us-east-1`.

3.  If you are using static credentials, remove the comments (`#`) from the lines that contain
    hidden `env` and `volumes` configurations.

4.  Apply the configuration to your cluster by using the following command from a terminal window:

    ```kubctl
    kubectl create --filename <external-dns-yaml> --namespace <your-namespace>
    ```

## Set DNS Names through Your Helm Chart for Flex Gateway

Use the `extraAnnotations` parameter with `helm upgrade` to set the domain names. This parameter is
described in the
[Helm chart for Flex Gateway (flex-gateway)](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Create a YAML configuration file to specify an ExternalDNS key and a comma-separated set of
    domain values.

    Replace the placeholder values `<domain-0>,…​,<domain-N>` with your domains:

    extraAnnotations: external-dns.alpha.kubernetes.io/hostname: <domain-0>,...,<domain-N>

2.  Use the `-f` option to pass your configuration file to the `helm upgrade` command.

    The command options to use depend on whether your registered gateway is deployed to a cluster:

    1.  If you are deploying Flex Gateway to the cluster for the first time, run the following
        command, replacing the placeholder values with the path to your gateway’s registration YAML
        file (by default, `registration.yaml`) and your domain names:

        ```helm
        helm -n gateway upgrade \
        -i --create-namespace \
        --wait ingress flex-gateway/flex-gateway \
        --set-file registration.content=<path-to-registration> \
        -f <your-YAML-config-file>
        ```

    2.  If you are updating a running gateway with the annotation, run the following command:

        ```helm
        helm -n gateway upgrade \
        --wait ingress flex-gateway/flex-gateway \
        --reuse-values \
        -f <your-YAML-config-file>
        ```

<!-- document id=07fe86728e8628adcb99936319091245106f655c93f97e5710c85ffd7ddc0967 url=/mulesoft/current/en-us/gateway/1.13/gateway-k8-external-dns.md -->

---
product: Omni Gateway
version: 1.13
---

# Provide a Domain Name for an Application on Your Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain name
instead of a difficult-to-understand external IP or random host name.

[ExternalDNS](https://github.com/kubernetes-sigs/external-dns/blob/master/README.md) is an open
source project that supports DNS configurations on many DNS providers. The tool is _not_ a DNS
server or provider. Instead, ExternalDNS discovers Kubernetes resources through public DNS servers
and configures the resources for supported DNS providers.

This guide uses ExternalDNS to configure domain names in an AWS Route 53 provider, which is one of
the stable providers supported by ExternalDNS.

## Before You Begin

Ensure that the following prerequisites are in place:

- A Kubernetes cluster on AWS

- An Omni Gateway deployment to an AWS cluster or a registered Omni Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up) or
  [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-k8-getting-started).

- An AWS Identity and Access Management (IAM) policy that allows ExternalDNS to update Amazon Route
  53 Resource Record Sets and Hosted Zones

  To use another target or create the IAM Policy with these permissions, see the
  [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/aws.md).

## Add ExternalDNS to Your Cluster

Add ExternalDNS (`external-dns`) to your cluster by creating and deploying a YAML configuration file
with the following content to your cluster:

1.  Create a YAML file with the following settings.

    ```yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: external-dns
      labels:
        app.kubernetes.io/name: external-dns
    spec:
      strategy:
        type: Recreate
      selector:
        matchLabels:
          app.kubernetes.io/name: external-dns
      template:
        metadata:
          labels:
            app.kubernetes.io/name: external-dns
        spec:
          containers:
            - name: external-dns
              image: registry.k8s.io/external-dns/external-dns:v0.13.1
              args:
                - --source=service
                - --source=ingress
                - --domain-filter=<your-domain> # makes only hosted zones visible
                - --provider=aws
                - --policy=upsert-only # prevents record deletion
                - --aws-zone-type=public # public zones only
                - --registry=txt
                - --txt-owner-id=my-hostedzone-identifier
              env:
                - name: AWS_DEFAULT_REGION
                  value: <aws-region> # sets the EKS region
          # # Uncomment the following settings when using static credentials
          #       - name: AWS_SHARED_CREDENTIALS_FILE
          #        value: /.aws/credentials
          #     volumeMounts:
          #       - name: aws-credentials
          #         mountPath: /.aws
          #         readOnly: true
          # volumes:
          #   - name: aws-credentials
          #     secret:
          #       secretName: external-dns
    ```

2.  In your new YAML file, set the following options, as needed, for your deployment:

    - `args` options:

      - `- --domain-filter=<your-domain>`: Make hosted zones that match your domain visible to
        ExternalDNS. Omit this option to process all available hosted zones.

        The option is critical for making `external-dns` work as intended.

      - `- --policy=upsert-only`: Prevent ExternalDNS from deleting any records. Omit this option to
        enable full synchronization.

      - `- --aws-zone-type=public`: Make only public hosted zones visible. Valid values are
        `public`, `private`, or no value for both types of zones.

    - `env` option `value: <aws-region>`: Set the region in which your EKS cluster is installed, for
      example, `us-east-1`.

3.  If you are using static credentials, remove the comments (`#`) from the lines that contain
    hidden `env` and `volumes` configurations.

4.  Apply the configuration to your cluster by using the following command from a terminal window:

    ```kubctl
    kubectl create --filename <external-dns-yaml> --namespace <your-namespace>
    ```

## Set DNS Names through Your Helm Chart for Omni Gateway

Use the `extraAnnotations` parameter with `helm upgrade` to set the domain names. This parameter is
described in the
[Helm chart for Omni Gateway (flex-gateway)](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Create a YAML configuration file to specify an ExternalDNS key and a comma-separated set of
    domain values.

    Replace the placeholder values `<domain-0>,…​,<domain-N>` with your domains:

    extraAnnotations: external-dns.alpha.kubernetes.io/hostname: <domain-0>,...,<domain-N>

2.  Use the `-f` option to pass your configuration file to the `helm upgrade` command.

    The command options to use depend on whether your registered gateway is deployed to a cluster:

    1.  If you are deploying Omni Gateway to the cluster for the first time, run the following
        command, replacing the placeholder values with the path to your gateway’s registration YAML
        file (by default, `registration.yaml`) and your domain names:

        ```helm
        helm -n gateway upgrade \
        -i --create-namespace \
        --wait ingress flex-gateway/flex-gateway \
        --set-file registration.content=<path-to-registration> \
        -f <your-YAML-config-file>
        ```

    2.  If you are updating a running gateway with the annotation, run the following command:

        ```helm
        helm -n gateway upgrade \
        --wait ingress flex-gateway/flex-gateway \
        --reuse-values \
        -f <your-YAML-config-file>
        ```

<!-- document id=b94e47d1b285d078e991715f9b6fff802e9fdf997571065665b2257e50fddf10 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-k8-external-dns.md -->

---
product: Omni Gateway
version: 1.9
---

# Provide a Domain Name for an Application on Your Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain name
instead of a difficult-to-understand external IP or random host name.

[ExternalDNS](https://github.com/kubernetes-sigs/external-dns/blob/master/README.md) is an open
source project that supports DNS configurations on many DNS providers. The tool is _not_ a DNS
server or provider. Instead, ExternalDNS discovers Kubernetes resources through public DNS servers
and configures the resources for supported DNS providers.

This guide uses ExternalDNS to configure domain names in an AWS Route 53 provider, which is one of
the stable providers supported by ExternalDNS.

## Before You Begin

Ensure that the following prerequisites are in place:

- A Kubernetes cluster on AWS

- A Flex Gateway deployment to an AWS cluster or a registered Flex Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up) or
  [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-getting-started).

- An AWS Identity and Access Management (IAM) policy that allows ExternalDNS to update Amazon Route
  53 Resource Record Sets and Hosted Zones

  To use another target or create the IAM Policy with these permissions, see the
  [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/aws.md).

## Add ExternalDNS to Your Cluster

Add ExternalDNS (`external-dns`) to your cluster by creating and deploying a YAML configuration file
with the following content to your cluster:

1.  Create a YAML file with the following settings.

    ```yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: external-dns
      labels:
        app.kubernetes.io/name: external-dns
    spec:
      strategy:
        type: Recreate
      selector:
        matchLabels:
          app.kubernetes.io/name: external-dns
      template:
        metadata:
          labels:
            app.kubernetes.io/name: external-dns
        spec:
          containers:
            - name: external-dns
              image: registry.k8s.io/external-dns/external-dns:v0.13.1
              args:
                - --source=service
                - --source=ingress
                - --domain-filter=<your-domain> # makes only hosted zones visible
                - --provider=aws
                - --policy=upsert-only # prevents record deletion
                - --aws-zone-type=public # public zones only
                - --registry=txt
                - --txt-owner-id=my-hostedzone-identifier
              env:
                - name: AWS_DEFAULT_REGION
                  value: <aws-region> # sets the EKS region
          # # Uncomment the following settings when using static credentials
          #       - name: AWS_SHARED_CREDENTIALS_FILE
          #        value: /.aws/credentials
          #     volumeMounts:
          #       - name: aws-credentials
          #         mountPath: /.aws
          #         readOnly: true
          # volumes:
          #   - name: aws-credentials
          #     secret:
          #       secretName: external-dns
    ```

2.  In your new YAML file, set the following options, as needed, for your deployment:

    - `args` options:

      - `- --domain-filter=<your-domain>`: Make hosted zones that match your domain visible to
        ExternalDNS. Omit this option to process all available hosted zones.

        The option is critical for making `external-dns` work as intended.

      - `- --policy=upsert-only`: Prevent ExternalDNS from deleting any records. Omit this option to
        enable full synchronization.

      - `- --aws-zone-type=public`: Make only public hosted zones visible. Valid values are
        `public`, `private`, or no value for both types of zones.

    - `env` option `value: <aws-region>`: Set the region in which your EKS cluster is installed, for
      example, `us-east-1`.

3.  If you are using static credentials, remove the comments (`#`) from the lines that contain
    hidden `env` and `volumes` configurations.

4.  Apply the configuration to your cluster by using the following command from a terminal window:

    ```kubctl
    kubectl create --filename <external-dns-yaml> --namespace <your-namespace>
    ```

## Set DNS Names through Your Helm Chart for Flex Gateway

Use the `extraAnnotations` parameter with `helm upgrade` to set the domain names. This parameter is
described in the
[Helm chart for Flex Gateway (flex-gateway)](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Create a YAML configuration file to specify an ExternalDNS key and a comma-separated set of
    domain values.

    Replace the placeholder values `<domain-0>,…​,<domain-N>` with your domains:

    extraAnnotations: external-dns.alpha.kubernetes.io/hostname: <domain-0>,...,<domain-N>

2.  Use the `-f` option to pass your configuration file to the `helm upgrade` command.

    The command options to use depend on whether your registered gateway is deployed to a cluster:

    1.  If you are deploying Flex Gateway to the cluster for the first time, run the following
        command, replacing the placeholder values with the path to your gateway’s registration YAML
        file (by default, `registration.yaml`) and your domain names:

        ```helm
        helm -n gateway upgrade \
        -i --create-namespace \
        --wait ingress flex-gateway/flex-gateway \
        --set-file registration.content=<path-to-registration> \
        -f <your-YAML-config-file>
        ```

    2.  If you are updating a running gateway with the annotation, run the following command:

        ```helm
        helm -n gateway upgrade \
        --wait ingress flex-gateway/flex-gateway \
        --reuse-values \
        -f <your-YAML-config-file>
        ```

<!-- document id=31a93d87be587594456f0e92bb7a3d8d638c65730cb3b2efea9233f77d42b177 url=/mulesoft/current/en-us/gateway/latest/gateway-k8-external-dns.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Provide a Domain Name for an Application on Your Kubernetes Cluster

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use ExternalDNS to expose an application or service on your Kubernetes cluster through a domain name
instead of a difficult-to-understand external IP or random host name.

[ExternalDNS](https://github.com/kubernetes-sigs/external-dns/blob/master/README.md) is an open
source project that supports DNS configurations on many DNS providers. The tool is _not_ a DNS
server or provider. Instead, ExternalDNS discovers Kubernetes resources through public DNS servers
and configures the resources for supported DNS providers.

This guide uses ExternalDNS to configure domain names in an AWS Route 53 provider, which is one of
the stable providers supported by ExternalDNS.

## Before You Begin

Ensure that the following prerequisites are in place:

- A Kubernetes cluster on AWS

- An Omni Gateway deployment to an AWS cluster or a registered Omni Gateway instance (gateway)

  For gateway registration and deployment processes, see
  [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up) or
  [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-k8-getting-started).

- An AWS Identity and Access Management (IAM) policy that allows ExternalDNS to update Amazon Route
  53 Resource Record Sets and Hosted Zones

  To use another target or create the IAM Policy with these permissions, see the
  [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/aws.md).

## Add ExternalDNS to Your Cluster

Add ExternalDNS (`external-dns`) to your cluster by creating and deploying a YAML configuration file
with the following content to your cluster:

1.  Create a YAML file with the following settings.

    ```yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: external-dns
      labels:
        app.kubernetes.io/name: external-dns
    spec:
      strategy:
        type: Recreate
      selector:
        matchLabels:
          app.kubernetes.io/name: external-dns
      template:
        metadata:
          labels:
            app.kubernetes.io/name: external-dns
        spec:
          containers:
            - name: external-dns
              image: registry.k8s.io/external-dns/external-dns:v0.13.1
              args:
                - --source=service
                - --source=ingress
                - --domain-filter=<your-domain> # makes only hosted zones visible
                - --provider=aws
                - --policy=upsert-only # prevents record deletion
                - --aws-zone-type=public # public zones only
                - --registry=txt
                - --txt-owner-id=my-hostedzone-identifier
              env:
                - name: AWS_DEFAULT_REGION
                  value: <aws-region> # sets the EKS region
          # # Uncomment the following settings when using static credentials
          #       - name: AWS_SHARED_CREDENTIALS_FILE
          #        value: /.aws/credentials
          #     volumeMounts:
          #       - name: aws-credentials
          #         mountPath: /.aws
          #         readOnly: true
          # volumes:
          #   - name: aws-credentials
          #     secret:
          #       secretName: external-dns
    ```

2.  In your new YAML file, set the following options, as needed, for your deployment:

    - `args` options:

      - `- --domain-filter=<your-domain>`: Make hosted zones that match your domain visible to
        ExternalDNS. Omit this option to process all available hosted zones.

        The option is critical for making `external-dns` work as intended.

      - `- --policy=upsert-only`: Prevent ExternalDNS from deleting any records. Omit this option to
        enable full synchronization.

      - `- --aws-zone-type=public`: Make only public hosted zones visible. Valid values are
        `public`, `private`, or no value for both types of zones.

    - `env` option `value: <aws-region>`: Set the region in which your EKS cluster is installed, for
      example, `us-east-1`.

3.  If you are using static credentials, remove the comments (`#`) from the lines that contain
    hidden `env` and `volumes` configurations.

4.  Apply the configuration to your cluster by using the following command from a terminal window:

    ```kubctl
    kubectl create --filename <external-dns-yaml> --namespace <your-namespace>
    ```

## Set DNS Names through Your Helm Chart for Omni Gateway

Use the `extraAnnotations` parameter with `helm upgrade` to set the domain names. This parameter is
described in the
[Helm chart for Omni Gateway (flex-gateway)](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway).

1.  Create a YAML configuration file to specify an ExternalDNS key and a comma-separated set of
    domain values.

    Replace the placeholder values `<domain-0>,…​,<domain-N>` with your domains:

    extraAnnotations: external-dns.alpha.kubernetes.io/hostname: <domain-0>,...,<domain-N>

2.  Use the `-f` option to pass your configuration file to the `helm upgrade` command.

    The command options to use depend on whether your registered gateway is deployed to a cluster:

    1.  If you are deploying Omni Gateway to the cluster for the first time, run the following
        command, replacing the placeholder values with the path to your gateway’s registration YAML
        file (by default, `registration.yaml`) and your domain names:

        ```helm
        helm -n gateway upgrade \
        -i --create-namespace \
        --wait ingress flex-gateway/flex-gateway \
        --set-file registration.content=<path-to-registration> \
        -f <your-YAML-config-file>
        ```

    2.  If you are updating a running gateway with the annotation, run the following command:

        ```helm
        helm -n gateway upgrade \
        --wait ingress flex-gateway/flex-gateway \
        --reuse-values \
        -f <your-YAML-config-file>
        ```

<!-- document id=22bce743b143445621f140b2df2d6774a0908a841fdf66c77058fe87e34e3634 url=/mulesoft/current/en-us/gateway/1.12/policies-custom-flex-getting-started.md -->

---
product: Omni Gateway
version: 1.12
---

# Publish a Flex Gateway Custom Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

The following steps are the high-level workflow for publishing custom policies for Anypoint Flex
Gateway:

1.  Create policy definition files.

2.  Publish policy definition asset to Exchange.

3.  Create implementation files.

4.  Add policy implementation to the published policy definition.

## Before You Begin

Before you can publish a custom policy for Flex Gateway, ensure you have administrator or
contributor permission for Anypoint Platform.

## Create Policy Definition Files

A JSON and a YAML policy definition file must be created before you can upload the policy
implementation. The required files are JSON and YAML.

The JSON file specifies the interface for the policy using JSON schema language. The JSON file is
used by API Manager to render the UI.

The YAML file provides metadata regarding the policy for example, the policy category, interface
scope, required characteristics, and RAML/OAS snippets.

Copy the custom policy definition examples or create the files on your local system.

### Create the JSON Schema File

The JSON schema file specifies the interface for the policy by identifying which properties are
required or supported to configure the policy. The file also includes more annotations to refine the
type for each property that enables some fields to perform a special behavior in the Anypoint
platform. For example, Dataweave validations or secure handling of secrets.

The JSON file must include the following fields:

- Top-level @context

  References the vocabulary used for the extra type annotations. The aliases used to namespace the
  vocabulary are a optional. Commonly-used names can be `security` or `config`.

  Values for the security and config aliases are:

  - Security: `anypoint://vocabulary/policy.yaml#`

  - Config: `` anypoint://vocabulary/policyConfigurationsForUI.yaml#` ``

- Top-level title

- $schema with a link to the JSON Schema spec (see example)

- Root type of `object`

- Top-level description

- Each property must also include:

  - Title

    The title is used by API Manager UI to render the field name.

  - Description

    The description is used by API Manager UI to describe the field.

  - Type

    Only primitive types are supported, for example `integer`, `string`, `object`, `boolean`, and
    `array`.

Each property can include the following:

- Format

  Options are `dataweaveExpression` and `` ipRange` ``.

- Default

  Allows the user to enter a default value which is rendered in the UI.

- @context with a @characteristics array

  Further refines the type with more annotations with the following options:

  - `config:commaSeparatedValues`

    The value of this field results in an array

  - `security:sensitive` Determines whether the property is masked when entering the property in the
    API Manager UI.

The following code is a example of a basic authentication JSON schema:

{ "title": "Basic authentication - Simple", "type": "object", "description": "Enforces HTTP Basic
authentication according to the details configured in the policy.", "properties": { "username": {
"title": "User Name", "type": "string" }, "password": { "title": "User Password", "type": "string",
"@context": { "@characteristics": \[ "security:sensitive" \] } } }, "required": \[ "username",
"password" \], "unevaluatedProperties": false, "@context": { "@vocab":
"anypoint://vocabulary/policy.yaml#", "security": "anypoint://vocabulary/policy.yaml#" },
"$id": "basic-authentication-simple",
  "$schema": "https://json-schema.org/draft/2019-09/schema" }

### Create the Definition Metadata YAML File

The YAML file provides information about the policy and its requirements. The YAML file is not tied
to any specific runtime or binary.

The file must have these fields configured:

- Header

  Header must be #%Policy Definition 0.1.

- Name

  User-friendly name used for to display the policy name in API Manager UI. Must be a string value.

- Description

  Must be a string value.

- Category

  Category to which the policy belongs. Used to group and filter policies in API Manager UI. Any
  string value is valid. For example, `security`, `quality of service`, `compliance`,
  `troubleshooting`, and `transformation`.

- Provided Characteristics

  A list used to define the characteristics the policy provides. Must be an array of strings. Use
  `providedCharacteristics: []` to leave empty.

The following code is an example of a basic authentication definition YAML file:

#%Policy Definition 0.1 name: Basic authentication - Simple description: Enforces HTTP Basic
authentication according to the details configured in the policy. category: Security
providedCharacteristics:

- Requires authentication requiredCharacteristics: \[\] interfaceScope: \["api", "resource"\]
  interfaceTransformation: \[\] encryptionSupported: true violationCategory: authentication

## Publish Policy Definition Asset to Exchange

After creating the required policy definition files (JSON and YAML), publish the policy definition
asset to Exchange.

See
[Create a Custom Policy Definition Asset](https://docs.mulesoft.com/exchange/to-create-an-asset#create-custom-policy-definition-asset)
for more information.

## Create Implementation Files

The policy implementation files that are required to make the policy available in a runtime are a
metadata file and a binary file. The metadata file describes what technology the binary file applies
to and from which runtime version. The metadata file must be a YAML file. The binary file contains
the policy logic and manages the runtime execution. The file can be a WebAssembly (WASM) for
Anypoint Flex Gateway or a JAR file for Mule 4 runtime.

### Create Metadata YAML File

The metadata YAML file provides details about the specific implementation of the policy definition.
A single policy definition can have several implementations. Each an independent asset in Exchange
or different versions of the same Exchange asset.

The metada YAML file must include the following fields:

- Header

  #%Policy Implementation 1.0

- Technology

  Either `mule4` or `flexGateway`.

- Name

  Name of the implementation.

- minRuntimeVersion

  A semantic version representing the first runtime version that the implementation binary is
  compatible with. For example, a mule binary might only be compatible from 4.3.0 onwards.

The YAML file can also include `Release notes`.

The following code is an example of a implementation metadata YAML file:

#%Policy Implementation 1.0 minRuntimeVersion: 4.1.1 maxRuntimeVersion: 4.4.0 technology: mule4
name: Simple Auth Mule Implementation releaseNotes: "<some notes here>"

### Create the Implementation Binary Files

The implementation binary file is a JAR file for Mule 4 policies or a WebAssembly WASM file for
Anypoint Flex Gateway. These files should support all of the configuration fields and function the
way the definition metadata describes.

## Add Policy Implementation Files to Published Policy Definition

After the custom policy definition asset is published to Exchange, the next step is to add the
policy implementation files to the published policy. This step enables the policy to be available in
runtime. The required implementation files are a binary file such as a WebAssembly (WASM) file for
Flex Gateway or JAR for Mule 4 runtime and a YAML metadata file.

Before adding the implementation files, ensure that the policy asset is in the Stable state.

## Apply the Policy to an API from Anypoint API Manager

After the implementation files are published, the policy is available to be applied to an API in API
Manager. See the Anypoint API Manager documentation for information about applying the policy.

<!-- document id=cbe37a29ddbff8375861b82af9a3f3e9c2899bf47c9f11e92d55100d24db6546 url=/mulesoft/current/en-us/gateway/1.9/policies-custom-flex-getting-started.md -->

---
product: Omni Gateway
version: 1.9
---

# Publish a Flex Gateway Custom Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Flex Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

The following steps are the high-level workflow for publishing custom policies for Anypoint Flex
Gateway:

1.  Create policy definition files.

2.  Publish policy definition asset to Exchange.

3.  Create implementation files.

4.  Add policy implementation to the published policy definition.

## Before You Begin

Before you can publish a custom policy for Flex Gateway, ensure you have administrator or
contributor permission for Anypoint Platform.

## Create Policy Definition Files

A JSON and a YAML policy definition file must be created before you can upload the policy
implementation. The required files are JSON and YAML.

The JSON file specifies the interface for the policy using JSON schema language. The JSON file is
used by API Manager to render the UI.

The YAML file provides metadata regarding the policy for example, the policy category, interface
scope, required characteristics, and RAML/OAS snippets.

Copy the custom policy definition examples or create the files on your local system.

### Create the JSON Schema File

The JSON schema file specifies the interface for the policy by identifying which properties are
required or supported to configure the policy. The file also includes more annotations to refine the
type for each property that enables some fields to perform a special behavior in the Anypoint
platform. For example, Dataweave validations or secure handling of secrets.

The JSON file must include the following fields:

- Top-level @context

  References the vocabulary used for the extra type annotations. The aliases used to namespace the
  vocabulary are a optional. Commonly-used names can be `security` or `config`.

  Values for the security and config aliases are:

  - Security: `anypoint://vocabulary/policy.yaml#`

  - Config: `` anypoint://vocabulary/policyConfigurationsForUI.yaml#` ``

- Top-level title

- $schema with a link to the JSON Schema spec (see example)

- Root type of `object`

- Top-level description

- Each property must also include:

  - Title

    The title is used by API Manager UI to render the field name.

  - Description

    The description is used by API Manager UI to describe the field.

  - Type

    Only primitive types are supported, for example `integer`, `string`, `object`, `boolean`, and
    `array`.

Each property can include the following:

- Format

  Options are `dataweaveExpression` and `` ipRange` ``.

- Default

  Allows the user to enter a default value which is rendered in the UI.

- @context with a @characteristics array

  Further refines the type with more annotations with the following options:

  - `config:commaSeparatedValues`

    The value of this field results in an array

  - `security:sensitive` Determines whether the property is masked when entering the property in the
    API Manager UI.

The following code is a example of a basic authentication JSON schema:

{ "title": "Basic authentication - Simple", "type": "object", "description": "Enforces HTTP Basic
authentication according to the details configured in the policy.", "properties": { "username": {
"title": "User Name", "type": "string" }, "password": { "title": "User Password", "type": "string",
"@context": { "@characteristics": \[ "security:sensitive" \] } } }, "required": \[ "username",
"password" \], "unevaluatedProperties": false, "@context": { "@vocab":
"anypoint://vocabulary/policy.yaml#", "security": "anypoint://vocabulary/policy.yaml#" },
"$id": "basic-authentication-simple",
  "$schema": "https://json-schema.org/draft/2019-09/schema" }

### Create the Definition Metadata YAML File

The YAML file provides information about the policy and its requirements. The YAML file is not tied
to any specific runtime or binary.

The file must have these fields configured:

- Header

  Header must be #%Policy Definition 0.1.

- Name

  User-friendly name used for to display the policy name in API Manager UI. Must be a string value.

- Description

  Must be a string value.

- Category

  Category to which the policy belongs. Used to group and filter policies in API Manager UI. Any
  string value is valid. For example, `security`, `quality of service`, `compliance`,
  `troubleshooting`, and `transformation`.

- Provided Characteristics

  A list used to define the characteristics the policy provides. Must be an array of strings. Use
  `providedCharacteristics: []` to leave empty.

The following code is an example of a basic authentication definition YAML file:

#%Policy Definition 0.1 name: Basic authentication - Simple description: Enforces HTTP Basic
authentication according to the details configured in the policy. category: Security
providedCharacteristics:

- Requires authentication requiredCharacteristics: \[\] interfaceScope: \["api", "resource"\]
  interfaceTransformation: \[\] encryptionSupported: true violationCategory: authentication

## Publish Policy Definition Asset to Exchange

After creating the required policy definition files (JSON and YAML), publish the policy definition
asset to Exchange.

See
[Create a Custom Policy Definition Asset](https://docs.mulesoft.com/exchange/to-create-an-asset#create-custom-policy-definition-asset)
for more information.

## Create Implementation Files

The policy implementation files that are required to make the policy available in a runtime are a
metadata file and a binary file. The metadata file describes what technology the binary file applies
to and from which runtime version. The metadata file must be a YAML file. The binary file contains
the policy logic and manages the runtime execution. The file can be a WebAssembly (WASM) for
Anypoint Flex Gateway or a JAR file for Mule 4 runtime.

### Create Metadata YAML File

The metadata YAML file provides details about the specific implementation of the policy definition.
A single policy definition can have several implementations. Each an independent asset in Exchange
or different versions of the same Exchange asset.

The metada YAML file must include the following fields:

- Header

  #%Policy Implementation 1.0

- Technology

  Either `mule4` or `flexGateway`.

- Name

  Name of the implementation.

- minRuntimeVersion

  A semantic version representing the first runtime version that the implementation binary is
  compatible with. For example, a mule binary might only be compatible from 4.3.0 onwards.

The YAML file can also include `Release notes`.

The following code is an example of a implementation metadata YAML file:

#%Policy Implementation 1.0 minRuntimeVersion: 4.1.1 maxRuntimeVersion: 4.4.0 technology: mule4
name: Simple Auth Mule Implementation releaseNotes: "<some notes here>"

### Create the Implementation Binary Files

The implementation binary file is a JAR file for Mule 4 policies or a WebAssembly WASM file for
Anypoint Flex Gateway. These files should support all of the configuration fields and function the
way the definition metadata describes.

## Add Policy Implementation Files to Published Policy Definition

After the custom policy definition asset is published to Exchange, the next step is to add the
policy implementation files to the published policy. This step enables the policy to be available in
runtime. The required implementation files are a binary file such as a WebAssembly (WASM) file for
Flex Gateway or JAR for Mule 4 runtime and a YAML metadata file.

Before adding the implementation files, ensure that the policy asset is in the Stable state.

## Apply the Policy to an API from Anypoint API Manager

After the implementation files are published, the policy is available to be applied to an API in API
Manager. See the Anypoint API Manager documentation for information about applying the policy.

<!-- document id=8b52093b027ce9fa739be7d068c752d551fc53d7125b77668221357d1c161436 url=/mulesoft/current/en-us/gateway/1.13/policies-custom-getting-started.md -->

---
product: Omni Gateway
version: 1.13
---

# Publish an Omni Gateway Custom Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

The following steps are the high-level workflow for publishing custom policies for Omni Gateway:

1.  Create policy definition files.

2.  Publish policy definition asset to Exchange.

3.  Create implementation files.

4.  Add policy implementation to the published policy definition.

## Before You Begin

Before you can publish a custom policy for Omni Gateway, ensure you have administrator or
contributor permission for Anypoint Platform.

## Create Policy Definition Files

A JSON and a YAML policy definition file must be created before you can upload the policy
implementation. The required files are JSON and YAML.

The JSON file specifies the interface for the policy using JSON schema language. The JSON file is
used by API Manager to render the UI.

The YAML file provides metadata regarding the policy for example, the policy category, interface
scope, required characteristics, and RAML/OAS snippets.

Copy the custom policy definition examples or create the files on your local system.

### Create the JSON Schema File

The JSON schema file specifies the interface for the policy by identifying which properties are
required or supported to configure the policy. The file also includes more annotations to refine the
type for each property that enables some fields to perform a special behavior in the Anypoint
platform. For example, Dataweave validations or secure handling of secrets.

The JSON file must include the following fields:

- Top-level @context

  References the vocabulary used for the extra type annotations. The aliases used to namespace the
  vocabulary are a optional. Commonly-used names can be `security` or `config`.

  Values for the security and config aliases are:

  - Security: `anypoint://vocabulary/policy.yaml#`

  - Config: `` anypoint://vocabulary/policyConfigurationsForUI.yaml#` ``

- Top-level title

- $schema with a link to the JSON Schema spec (see example)

- Root type of `object`

- Top-level description

- Each property must also include:

  - Title

    The title is used by API Manager UI to render the field name.

  - Description

    The description is used by API Manager UI to describe the field.

  - Type

    Only primitive types are supported, for example `integer`, `string`, `object`, `boolean`, and
    `array`.

Each property can include the following:

- Format

  Options are `dataweaveExpression` and `` ipRange` ``.

- Default

  Allows the user to enter a default value which is rendered in the UI.

- @context with a @characteristics array

  Further refines the type with more annotations with the following options:

  - `config:commaSeparatedValues`

    The value of this field results in an array

  - `security:sensitive` Determines whether the property is masked when entering the property in the
    API Manager UI.

The following code is a example of a basic authentication JSON schema:

{ "title": "Basic authentication - Simple", "type": "object", "description": "Enforces HTTP Basic
authentication according to the details configured in the policy.", "properties": { "username": {
"title": "User Name", "type": "string" }, "password": { "title": "User Password", "type": "string",
"@context": { "@characteristics": \[ "security:sensitive" \] } } }, "required": \[ "username",
"password" \], "unevaluatedProperties": false, "@context": { "@vocab":
"anypoint://vocabulary/policy.yaml#", "security": "anypoint://vocabulary/policy.yaml#" },
"$id": "basic-authentication-simple",
  "$schema": "https://json-schema.org/draft/2019-09/schema" }

### Create the Definition Metadata YAML File

The YAML file provides information about the policy and its requirements. The YAML file is not tied
to any specific runtime or binary.

The file must have these fields configured:

- Header

  Header must be #%Policy Definition 0.1.

- Name

  User-friendly name used for to display the policy name in API Manager UI. Must be a string value.

- Description

  Must be a string value.

- Category

  Category to which the policy belongs. Used to group and filter policies in API Manager UI. Any
  string value is valid. For example, `security`, `quality of service`, `compliance`,
  `troubleshooting`, and `transformation`.

- Provided Characteristics

  A list used to define the characteristics the policy provides. Must be an array of strings. Use
  `providedCharacteristics: []` to leave empty.

The following code is an example of a basic authentication definition YAML file:

#%Policy Definition 0.1 name: Basic authentication - Simple description: Enforces HTTP Basic
authentication according to the details configured in the policy. category: Security
providedCharacteristics:

- Requires authentication requiredCharacteristics: \[\] interfaceScope: \["api", "resource"\]
  interfaceTransformation: \[\] encryptionSupported: true violationCategory: authentication

## Publish Policy Definition Asset to Exchange

After creating the required policy definition files (JSON and YAML), publish the policy definition
asset to Exchange.

See
[Create a Custom Policy Definition Asset](https://docs.mulesoft.com/exchange/to-create-an-asset#create-custom-policy-definition-asset)
for more information.

## Create Implementation Files

The policy implementation files that are required to make the policy available in a runtime are a
metadata file and a binary file. The metadata file describes what technology the binary file applies
to and from which runtime version. The metadata file must be a YAML file. The binary file contains
the policy logic and manages the runtime execution. The file can be a WebAssembly (WASM) for Omni
Gateway or a JAR file for Mule 4 runtime.

### Create Metadata YAML File

The metadata YAML file provides details about the specific implementation of the policy definition.
A single policy definition can have several implementations. Each an independent asset in Exchange
or different versions of the same Exchange asset.

The metada YAML file must include the following fields:

- Header

  #%Policy Implementation 1.0

- Technology

  Either `mule4` or `flexGateway`.

- Name

  Name of the implementation.

- minRuntimeVersion

  A semantic version representing the first runtime version that the implementation binary is
  compatible with. For example, a mule binary might only be compatible from 4.3.0 onwards.

The YAML file can also include `Release notes`.

The following code is an example of a implementation metadata YAML file:

#%Policy Implementation 1.0 minRuntimeVersion: 4.1.1 maxRuntimeVersion: 4.4.0 technology: mule4
name: Simple Auth Mule Implementation releaseNotes: "<some notes here>"

### Create the Implementation Binary Files

The implementation binary file is a JAR file for Mule 4 policies or a WebAssembly WASM file for Omni
Gateway. These files should support all of the configuration fields and function the way the
definition metadata describes.

## Add Policy Implementation Files to Published Policy Definition

After the custom policy definition asset is published to Exchange, the next step is to add the
policy implementation files to the published policy. This step enables the policy to be available in
runtime. The required implementation files are a binary file such as a WebAssembly (WASM) file for
Omni Gateway or JAR for Mule 4 runtime and a YAML metadata file.

Before adding the implementation files, ensure that the policy asset is in the Stable state.

## Apply the Policy to an API from Anypoint API Manager

After the implementation files are published, the policy is available to be applied to an API in API
Manager. See the Anypoint API Manager documentation for information about applying the policy.

<!-- document id=d426790cde3c9a4afcef1c79e541a63741c521665746e606ba7bc371ffca17ef url=/mulesoft/current/en-us/gateway/latest/policies-custom-getting-started.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Publish an Omni Gateway Custom Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

**New Feature Available**: This product feature is outdated and is only provided for existing custom
policies. To create new custom policies, use the
[Omni Gateway Policy Development Kit (PDK)](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

The following steps are the high-level workflow for publishing custom policies for Omni Gateway:

1.  Create policy definition files.

2.  Publish policy definition asset to Exchange.

3.  Create implementation files.

4.  Add policy implementation to the published policy definition.

## Before You Begin

Before you can publish a custom policy for Omni Gateway, ensure you have administrator or
contributor permission for Anypoint Platform.

## Create Policy Definition Files

A JSON and a YAML policy definition file must be created before you can upload the policy
implementation. The required files are JSON and YAML.

The JSON file specifies the interface for the policy using JSON schema language. The JSON file is
used by API Manager to render the UI.

The YAML file provides metadata regarding the policy for example, the policy category, interface
scope, required characteristics, and RAML/OAS snippets.

Copy the custom policy definition examples or create the files on your local system.

### Create the JSON Schema File

The JSON schema file specifies the interface for the policy by identifying which properties are
required or supported to configure the policy. The file also includes more annotations to refine the
type for each property that enables some fields to perform a special behavior in the Anypoint
platform. For example, Dataweave validations or secure handling of secrets.

The JSON file must include the following fields:

- Top-level @context

  References the vocabulary used for the extra type annotations. The aliases used to namespace the
  vocabulary are a optional. Commonly-used names can be `security` or `config`.

  Values for the security and config aliases are:

  - Security: `anypoint://vocabulary/policy.yaml#`

  - Config: `` anypoint://vocabulary/policyConfigurationsForUI.yaml#` ``

- Top-level title

- $schema with a link to the JSON Schema spec (see example)

- Root type of `object`

- Top-level description

- Each property must also include:

  - Title

    The title is used by API Manager UI to render the field name.

  - Description

    The description is used by API Manager UI to describe the field.

  - Type

    Only primitive types are supported, for example `integer`, `string`, `object`, `boolean`, and
    `array`.

Each property can include the following:

- Format

  Options are `dataweaveExpression` and `` ipRange` ``.

- Default

  Allows the user to enter a default value which is rendered in the UI.

- @context with a @characteristics array

  Further refines the type with more annotations with the following options:

  - `config:commaSeparatedValues`

    The value of this field results in an array

  - `security:sensitive` Determines whether the property is masked when entering the property in the
    API Manager UI.

The following code is a example of a basic authentication JSON schema:

{ "title": "Basic authentication - Simple", "type": "object", "description": "Enforces HTTP Basic
authentication according to the details configured in the policy.", "properties": { "username": {
"title": "User Name", "type": "string" }, "password": { "title": "User Password", "type": "string",
"@context": { "@characteristics": \[ "security:sensitive" \] } } }, "required": \[ "username",
"password" \], "unevaluatedProperties": false, "@context": { "@vocab":
"anypoint://vocabulary/policy.yaml#", "security": "anypoint://vocabulary/policy.yaml#" },
"$id": "basic-authentication-simple",
  "$schema": "https://json-schema.org/draft/2019-09/schema" }

### Create the Definition Metadata YAML File

The YAML file provides information about the policy and its requirements. The YAML file is not tied
to any specific runtime or binary.

The file must have these fields configured:

- Header

  Header must be #%Policy Definition 0.1.

- Name

  User-friendly name used for to display the policy name in API Manager UI. Must be a string value.

- Description

  Must be a string value.

- Category

  Category to which the policy belongs. Used to group and filter policies in API Manager UI. Any
  string value is valid. For example, `security`, `quality of service`, `compliance`,
  `troubleshooting`, and `transformation`.

- Provided Characteristics

  A list used to define the characteristics the policy provides. Must be an array of strings. Use
  `providedCharacteristics: []` to leave empty.

The following code is an example of a basic authentication definition YAML file:

#%Policy Definition 0.1 name: Basic authentication - Simple description: Enforces HTTP Basic
authentication according to the details configured in the policy. category: Security
providedCharacteristics:

- Requires authentication requiredCharacteristics: \[\] interfaceScope: \["api", "resource"\]
  interfaceTransformation: \[\] encryptionSupported: true violationCategory: authentication

## Publish Policy Definition Asset to Exchange

After creating the required policy definition files (JSON and YAML), publish the policy definition
asset to Exchange.

See
[Create a Custom Policy Definition Asset](https://docs.mulesoft.com/exchange/to-create-an-asset#create-custom-policy-definition-asset)
for more information.

## Create Implementation Files

The policy implementation files that are required to make the policy available in a runtime are a
metadata file and a binary file. The metadata file describes what technology the binary file applies
to and from which runtime version. The metadata file must be a YAML file. The binary file contains
the policy logic and manages the runtime execution. The file can be a WebAssembly (WASM) for Omni
Gateway or a JAR file for Mule 4 runtime.

### Create Metadata YAML File

The metadata YAML file provides details about the specific implementation of the policy definition.
A single policy definition can have several implementations. Each an independent asset in Exchange
or different versions of the same Exchange asset.

The metada YAML file must include the following fields:

- Header

  #%Policy Implementation 1.0

- Technology

  Either `mule4` or `flexGateway`.

- Name

  Name of the implementation.

- minRuntimeVersion

  A semantic version representing the first runtime version that the implementation binary is
  compatible with. For example, a mule binary might only be compatible from 4.3.0 onwards.

The YAML file can also include `Release notes`.

The following code is an example of a implementation metadata YAML file:

#%Policy Implementation 1.0 minRuntimeVersion: 4.1.1 maxRuntimeVersion: 4.4.0 technology: mule4
name: Simple Auth Mule Implementation releaseNotes: "<some notes here>"

### Create the Implementation Binary Files

The implementation binary file is a JAR file for Mule 4 policies or a WebAssembly WASM file for Omni
Gateway. These files should support all of the configuration fields and function the way the
definition metadata describes.

## Add Policy Implementation Files to Published Policy Definition

After the custom policy definition asset is published to Exchange, the next step is to add the
policy implementation files to the published policy. This step enables the policy to be available in
runtime. The required implementation files are a binary file such as a WebAssembly (WASM) file for
Omni Gateway or JAR for Mule 4 runtime and a YAML metadata file.

Before adding the implementation files, ensure that the policy asset is in the Stable state.

## Apply the Policy to an API from Anypoint API Manager

After the implementation files are published, the policy is available to be applied to an API in API
Manager. See the Anypoint API Manager documentation for information about applying the policy.

<!-- document id=edce821474b8d4389a9cc9393472cb0e27343f84826902485866f1a802348e7a url=/mulesoft/current/en-us/gateway/1.9/flex-local-publish-simple-api.md -->

---
product: Omni Gateway
version: 1.9
---

# Publishing a Simple API in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish a simple API running behind Flex Gateway in Local Mode, modifying YAML configuration data by
one of the following methods:

- Linux and Docker: `.yaml` files

- Kubernetes: `kubectl apply`

The following procedures demonstrate applying a simple YAML configuration for an unsecured API with
a single upstream service.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Flex Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in Local Mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for more information.

- Flex Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run) for more information.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in Local Mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for
  more information about installing and running the gateway.

- A Docker image stored in a Docker repository. The following example refers to a fictional
  `orders-api` application, but you can specify your own Docker repository and Docker image in the
  `Deployment` configuration resource (in `spec.spec.image`).

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Using the `kubectl apply` command, install a Docker image named "orders-api" from a given
    repository.

    The following YAML snippet defines two configuration resources: `Service`, and `Deployment`. The
    `Service` resource declares the `orders-api` service. The `Deployment` resource declares the
    desired deployment state by specifying information such as the number of replicas to create, and
    the Docker image to sideload.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: v1 kind: Service metadata: name: orders-api labels: app: orders-api service:
    orders-api spec: ports:
    - name: http port: 80 targetPort: http selector: app: orders-api

    ***

    apiVersion: apps/v1 kind: Deployment metadata: name: orders-api spec: replicas: 1 selector:
    matchLabels: app: orders-api version: v1 template: metadata: labels: app: orders-api version: v1
    spec: containers: - image: <repository>/<dockerfile> imagePullPolicy: IfNotPresent name:
    orders-api ports: - name: http containerPort: 3000 resources: limits: cpu: 100m memory: 64Mi EOF

2.  Again using `kubectl apply`, create the ingress to route traffic.

    The following YAML example defines one configuration resource: `Ingress`.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: orders-api spec:
    ingressClassName: ingress-http.gateway rules:
    - http: paths:
      - path: /api/orders(/.\*) pathType: ImplementationSpecific backend: service: name: orders-api
        port: number: 80 EOF

A simple API is now running behind Flex Gateway.

<!-- document id=cf1c40e28cc451e00b0c931d69c218ed14b45b1a1a6f66f97057839c175384ec url=/mulesoft/current/en-us/gateway/1.12/flex-local-publish-simple-api.md -->

---
product: Omni Gateway
version: 1.12
---

# Publishing a Simple API Instance in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish a simple API running behind Flex Gateway in Local Mode, modifying YAML configuration data by
one of the following methods:

- Linux and Docker: `.yaml` files

- Kubernetes: `kubectl apply`

The following procedures demonstrate applying a simple YAML configuration for an unsecured API with
a single upstream service.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Flex Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in Local Mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for more information.

- Flex Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run) for more information.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in Local Mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for
  more information about installing and running the gateway.

- A Docker image stored in a Docker repository. The following example refers to a fictional
  `orders-api` application, but you can specify your own Docker repository and Docker image in the
  `Deployment` configuration resource (in `spec.spec.image`).

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Using the `kubectl apply` command, install a Docker image named "orders-api" from a given
    repository.

    The following YAML snippet defines two configuration resources: `Service`, and `Deployment`. The
    `Service` resource declares the `orders-api` service. The `Deployment` resource declares the
    desired deployment state by specifying information such as the number of replicas to create, and
    the Docker image to sideload.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: v1 kind: Service metadata: name: orders-api labels: app: orders-api service:
    orders-api spec: ports:
    - name: http port: 80 targetPort: http selector: app: orders-api

    ***

    apiVersion: apps/v1 kind: Deployment metadata: name: orders-api spec: replicas: 1 selector:
    matchLabels: app: orders-api version: v1 template: metadata: labels: app: orders-api version: v1
    spec: containers: - image: <repository>/<dockerfile> imagePullPolicy: IfNotPresent name:
    orders-api ports: - name: http containerPort: 3000 resources: limits: cpu: 100m memory: 64Mi EOF

2.  Again using `kubectl apply`, create the ingress to route traffic.

    The following YAML example defines one configuration resource: `Ingress`.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: orders-api spec:
    ingressClassName: ingress-http.gateway rules:
    - http: paths:
      - path: /api/orders(/.\*) pathType: ImplementationSpecific backend: service: name: orders-api
        port: number: 80 EOF

A simple API is now running behind Flex Gateway.

<!-- document id=e9f5e9f232abb2f0fdbb6b7ada5ad1f114c6a466c04b4a4ff1c95cb786872e40 url=/mulesoft/current/en-us/gateway/1.13/local-publish-simple-api.md -->

---
product: Omni Gateway
version: 1.13
---

# Publishing a Simple API Instance in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish a simple API running behind Omni Gateway in Local Mode, modifying YAML configuration data by
one of the following methods:

- Linux and Docker: `.yaml` files

- Kubernetes: `kubectl apply`

The following procedures demonstrate applying a simple YAML configuration for an unsecured API with
a single upstream service.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Omni Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in Local Mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more
  information about installing and running the gateway.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more information.

- Omni Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run) for more information.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in Local Mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more
  information about installing and running the gateway.

- A Docker image stored in a Docker repository. The following example refers to a fictional
  `orders-api` application, but you can specify your own Docker repository and Docker image in the
  `Deployment` configuration resource (in `spec.spec.image`).

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Using the `kubectl apply` command, install a Docker image named "orders-api" from a given
    repository.

    The following YAML snippet defines two configuration resources: `Service`, and `Deployment`. The
    `Service` resource declares the `orders-api` service. The `Deployment` resource declares the
    desired deployment state by specifying information such as the number of replicas to create, and
    the Docker image to sideload.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: v1 kind: Service metadata: name: orders-api labels: app: orders-api service:
    orders-api spec: ports:
    - name: http port: 80 targetPort: http selector: app: orders-api

    ***

    apiVersion: apps/v1 kind: Deployment metadata: name: orders-api spec: replicas: 1 selector:
    matchLabels: app: orders-api version: v1 template: metadata: labels: app: orders-api version: v1
    spec: containers: - image: <repository>/<dockerfile> imagePullPolicy: IfNotPresent name:
    orders-api ports: - name: http containerPort: 3000 resources: limits: cpu: 100m memory: 64Mi EOF

2.  Again using `kubectl apply`, create the ingress to route traffic.

    The following YAML example defines one configuration resource: `Ingress`.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: orders-api spec:
    ingressClassName: ingress-http.gateway rules:
    - http: paths:
      - path: /api/orders(/.\*) pathType: ImplementationSpecific backend: service: name: orders-api
        port: number: 80 EOF

A simple API is now running behind Omni Gateway.

<!-- document id=6f6a4d9355fdbcc76930aba5ceff9f342b678f5fc86b87be0afbf14911ae0734 url=/mulesoft/current/en-us/gateway/latest/local-publish-simple-api.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Publishing a Simple API Instance in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish a simple API running behind Omni Gateway in Local Mode, modifying YAML configuration data by
one of the following methods:

- Linux and Docker: `.yaml` files

- Kubernetes: `kubectl apply`

The following procedures demonstrate applying a simple YAML configuration for an unsecured API with
a single upstream service.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Omni Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in Local Mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more
  information about installing and running the gateway.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more information.

- Omni Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run) for more information.

- Your upstream service URL. The following example refers to a fictional `orders-api` service, but
  you can specify your own API name in `metadata.name` and your service details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: orders-api spec:
    address: http://0.0.0.0:8080 services: orders: address: https://<your orders URL>:<your port>/
    routes: - rules: - path: /api/orders(/.\*)

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/animal-facts-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/orders(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:orders-api-orders
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating service
    monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/orders-api-orders
    https://<your orders URL>:<your port>/ \[agent\]\[debug\] generating service
    orders-api-orders.default.svc hostname: <your orders URL> port: <your port> \[agent\]\[info\]
    Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\] cds: add 2
    cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s), skipped 1
    unmodified cluster(s)

A simple API is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in Local Mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more
  information about installing and running the gateway.

- A Docker image stored in a Docker repository. The following example refers to a fictional
  `orders-api` application, but you can specify your own Docker repository and Docker image in the
  `Deployment` configuration resource (in `spec.spec.image`).

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Using the `kubectl apply` command, install a Docker image named "orders-api" from a given
    repository.

    The following YAML snippet defines two configuration resources: `Service`, and `Deployment`. The
    `Service` resource declares the `orders-api` service. The `Deployment` resource declares the
    desired deployment state by specifying information such as the number of replicas to create, and
    the Docker image to sideload.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: v1 kind: Service metadata: name: orders-api labels: app: orders-api service:
    orders-api spec: ports:
    - name: http port: 80 targetPort: http selector: app: orders-api

    ***

    apiVersion: apps/v1 kind: Deployment metadata: name: orders-api spec: replicas: 1 selector:
    matchLabels: app: orders-api version: v1 template: metadata: labels: app: orders-api version: v1
    spec: containers: - image: <repository>/<dockerfile> imagePullPolicy: IfNotPresent name:
    orders-api ports: - name: http containerPort: 3000 resources: limits: cpu: 100m memory: 64Mi EOF

2.  Again using `kubectl apply`, create the ingress to route traffic.

    The following YAML example defines one configuration resource: `Ingress`.

    cat <<EOF | kubectl apply -f -
    ---

    apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: orders-api spec:
    ingressClassName: ingress-http.gateway rules:
    - http: paths:
      - path: /api/orders(/.\*) pathType: ImplementationSpecific backend: service: name: orders-api
        port: number: 80 EOF

A simple API is now running behind Omni Gateway.

<!-- document id=221fbd30749bb783ffe37d36561d713be17989b6bce8a6cb04bfb4d8c49321c5 url=/mulesoft/current/en-us/gateway/1.12/flex-local-publish-api-multiple-services.md -->

---
product: Omni Gateway
version: 1.12
---

# Publishing an API Instance with Multiple Upstream Services in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Flex Gateway manages traffic by using multiple routes with a defined route order and individual
rulesets to direct traffic to different sets of upstream services. Each API instance supports
multiple routes that can each direct traffic to multiple upstream services.

For Flex Gateways running in Local Mode, API instances with multiple upstream services are
configured by using the `ApiInstance` and the `PolicyBinding` YAML configuration resources. The
`ApiInstance` resource defines an API instance, and the `route-weighted` policy resource defines a
single route to one or multiple upstream services. To add additional routes, add multiple
`route-weighted` resources.

The following tutorials use a preconfigured `route-weighted` policy resource. For information about
how to configure the resource, see
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.12/policies-included-traffic-management).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Flex Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Flex Gateway. For more information, see [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install).

- Registered Flex Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting the configuration field
    values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services now runs behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Flex Gateway. For more information, see [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install).

- Registered Flex Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting configuration fields with
    your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Flex Gateway. For more information, see [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install).

- Registered Flex Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

- Your upstream service URLs.

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Use the `kubectl apply` command to apply the following `.yaml` configuration file, substituting
    the configuration field values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

2.  Enter the following command to view the pods logs and ensure that the API was created
    successfully:

kubectl logs -f <pod-name>

<!-- document id=6116c5ae0deb41f6c59c9a8fa76dee3cba2636b6321453ffe6bb3cd09fde2753 url=/mulesoft/current/en-us/gateway/1.13/local-publish-api-multiple-services.md -->

---
product: Omni Gateway
version: 1.13
---

# Publishing an API Instance with Multiple Upstream Services in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Omni Gateway manages traffic by using multiple routes with a defined route order and individual
rulesets to direct traffic to different sets of upstream services. Each API instance supports
multiple routes that can each direct traffic to multiple upstream services.

For Omni Gateways running in Local Mode, API instances with multiple upstream services are
configured by using the `ApiInstance` and the `PolicyBinding` YAML configuration resources. The
`ApiInstance` resource defines an API instance, and the `route-weighted` policy resource defines a
single route to one or multiple upstream services. To add additional routes, add multiple
`route-weighted` resources.

The following tutorials use a preconfigured `route-weighted` policy resource. For information about
how to configure the resource, see
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.13/policies-included-traffic-management).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Omni Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Omni Gateway. For more information, see [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install).

- Registered Omni Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting the configuration field
    values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services now runs behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Omni Gateway. For more information, see [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install).

- Registered Omni Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting configuration fields with
    your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Omni Gateway. For more information, see [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install).

- Registered Omni Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

- Your upstream service URLs.

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Use the `kubectl apply` command to apply the following `.yaml` configuration file, substituting
    the configuration field values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

2.  Enter the following command to view the pods logs and ensure that the API was created
    successfully:

kubectl logs -f <pod-name>

<!-- document id=303198bc1f5fce25950fc9cb1d0e097bc0194eee665913bdf6eb3c013c243666 url=/mulesoft/current/en-us/gateway/latest/local-publish-api-multiple-services.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Publishing an API Instance with Multiple Upstream Services in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Omni Gateway manages traffic by using multiple routes with a defined route order and individual
rulesets to direct traffic to different sets of upstream services. Each API instance supports
multiple routes that can each direct traffic to multiple upstream services.

For Omni Gateways running in Local Mode, API instances with multiple upstream services are
configured by using the `ApiInstance` and the `PolicyBinding` YAML configuration resources. The
`ApiInstance` resource defines an API instance, and the `route-weighted` policy resource defines a
single route to one or multiple upstream services. To add additional routes, add multiple
`route-weighted` resources.

The following tutorials use a preconfigured `route-weighted` policy resource. For information about
how to configure the resource, see
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Omni Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Omni Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Omni Gateway. For more information, see [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install).

- Registered Omni Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting the configuration field
    values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services now runs behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Omni Gateway. For more information, see [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install).

- Registered Omni Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting configuration fields with
    your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Omni Gateway. For more information, see [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install).

- Registered Omni Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

- Your upstream service URLs.

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Use the `kubectl apply` command to apply the following `.yaml` configuration file, substituting
    the configuration field values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

2.  Enter the following command to view the pods logs and ensure that the API was created
    successfully:

kubectl logs -f <pod-name>

<!-- document id=6f15dc8de30a283adc868bcb225191102ba0ac4cc61ee3b52044546cfae0b17b url=/mulesoft/current/en-us/gateway/1.9/flex-local-publish-api-multiple-services.md -->

---
product: Omni Gateway
version: 1.9
---

# Publishing an API with Multiple Upstream Services in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Flex Gateway manages traffic by using multiple routes with a defined route order and individual
rulesets to direct traffic to different sets of upstream services. Each API instance supports
multiple routes that can each direct traffic to multiple upstream services.

For Flex Gateways running in Local Mode, API instances with multiple upstream services are
configured by using the `ApiInstance` and the `PolicyBinding` YAML configuration resources. The
`ApiInstance` resource defines an API instance, and the `route-weighted` policy resource defines a
single route to one or multiple upstream services. To add additional routes, add multiple
`route-weighted` resources.

The following tutorials use a preconfigured `route-weighted` policy resource. For information about
how to configure the resource, see
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.9/policies-included-traffic-management).

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Publish an API Running Behind Flex Gateway on Linux</a></p></div></div></td><td><div><div><p><a href="#docker">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Publish an API Running Behind Flex Gateway in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Flex Gateway. For more information, see [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install).

- Registered Flex Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting the configuration field
    values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services now runs behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Flex Gateway. For more information, see [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install).

- Registered Flex Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

- Your upstream service URLs.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting configuration fields with
    your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service Name:products-users-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host:
    path:/api/users(/.\*) methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-users Namespace:default} \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Policy default/envoy.filters.http.router \[agent\]\[info\] Gateway default/18b4e890fe7d:
    Adding Service default/monitoring\_metrics http://0.0.0.0:9881 \[agent\]\[debug\] generating
    service monitoring\_metrics.default.svc hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Service default/products-users-api-products
    https://<your products URL>:<your port>/ \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    Service default/products-users-api-users https://<your users URL>:<your port>/
    \[agent\]\[debug\] generating service products-users-api-products.default.svc hostname:
    <your products URL> port: <your port> \[agent\]\[debug\] generating service
    products-users-api-users.default.svc hostname: <your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\] cds: added/updated 1 cluster(s),
    skipped 1 unmodified cluster(s)

An API with multiple upstream services is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Kubernetes Cluster

### Before You Begin

Before getting started, ensure that you have:

- Downloaded Flex Gateway. For more information, see [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install).

- Registered Flex Gateway and are running it in Local Mode. For more information, see
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

- Your upstream service URLs.

If you use [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) as
an upstream service or you apply a policy that makes requests to a Kubernetes Service, set the
following parameters in the `service` resource:

- `spec.ports[].protocol` to `TCP`

- `spec.ports[].name`

Your `spec.ports[].name` service must adhere to the `<protocol>[-<suffix>]` structure. `[-<suffix>]`
is optional, and the valid options for `<protocol>` are:

- HTTP

- H2

- HTTPS

### Publish an API

1.  Use the `kubectl apply` command to apply the following `.yaml` configuration file, substituting
    the configuration field values with your values.

    The snippet refers to the fictional `products-api` and `products-api-beta` services and a
    fictional `json-http` API instance. Specify your own API name and your own service details:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-http spec:
    address: http://0.0.0.0:8080/json ​
    ---

    ​ apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    weight-routing-test spec: targetRef: name: json-http policyRef: name: route-weighted config:
    routes: - weight: 75 # max\_value=100, min\_value=1 destinationPath: /posts/ destinationRef:
    name: products-api - weight: 25 destinationPath: /posts/ destinationRef: name: products-api-beta
    rules:
    - path: (.\*) methods: POST headers: x-test: true host: test.com
    - methods: GET|POST headers: x-test: true y-test: false host: test.com

2.  Enter the following command to view the pods logs and ensure that the API was created
    successfully:

kubectl logs -f <pod-name>

<!-- document id=e24e0bf11e149a01accd6e1c66428a95dc276c71dbe584ebf186597020b90b52 url=/mulesoft/current/en-us/gateway/1.12/flex-agent-publish-apis.md -->

---
product: Omni Gateway
version: 1.12
---

# Publishing Flex Gateway Agent and Tool instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Similar to API instances, use **API Manager** to publish Agent, MCP, and LLM instances for Managed
Flex Gateway or Flex Gateway running in Connected Mode.

For more information, see
[Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool).

## See Also

- [Publishing Managed Gateway and Connected Mode API Instances](https://docs.mulesoft.com/gateway/1.12/flex-gateway-publish-apis-conn)

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

<!-- document id=f958977a73c29341a1597d658002bcad7d4302cc6bc7a19f248d5bb8843f9def url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-publish-apis.md -->

---
product: Omni Gateway
version: 1.12
---

# Publishing Flex Gateway API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publishing an API instance consists of defining a client service and routing that service to a
backend location. Flex Gateway enables you to publish API instances via Anypoint Platform (Connected
Mode) or declarative configuration files (Local Mode).

To publish an API instance in Connected Mode, see
[Publishing Managed Gateway and Connected Mode API Instances](https://docs.mulesoft.com/gateway/1.12/flex-gateway-publish-apis-conn).

To publish an API instance in Local Mode, see
[Publishing Local Mode API Instances](https://docs.mulesoft.com/gateway/1.12/flex-gateway-publish-apis-local).

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

<!-- document id=f56fa32790731c4448b51cff8ed70f5c3bbc3af8866983b795d1741e1d7f1b61 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-publish-apis.md -->

---
product: Omni Gateway
version: 1.9
---

# Publishing Flex Gateway APIs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publishing an API consists of defining a client service and routing that service to a backend
location. Flex Gateway enables you to publish APIs via Anypoint Platform (Connected Mode) or
declarative configuration files (Local Mode).

To publish an API in Connected Mode, see
[Publishing Managed Gateway and Connected Mode APIs](https://docs.mulesoft.com/gateway/1.9/flex-gateway-publish-apis-conn).

To publish an API in Local Mode, see [Publishing Local Mode APIs](https://docs.mulesoft.com/gateway/1.9/flex-gateway-publish-apis-local).

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

<!-- document id=9f82ccf729e7b349774f7ac3a07331304d909f3bdbe27b27bca070c6a6c165cc url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-publish-apis-local.md -->

---
product: Omni Gateway
version: 1.12
---

# Publishing Local Mode API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Flex Gateway running in Local Mode, you publish API instances using
[local declarative configuration files](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide). You specify the
location of these configuration files when you first run Flex Gateway.

For more information about how to run the gateway, see
[Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run).

Refer to these tutorials for examples on publishing APIs in Local Mode:

- [Publishing a Simple API Instance in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-publish-simple-api)

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-publish-api-multiple-services)

<!-- document id=0c0740b36f65c034fa9b840f25a20d70cc24156c5999034f0ed26a2486c53559 url=/mulesoft/current/en-us/gateway/1.13/gateway-publish-apis-local.md -->

---
product: Omni Gateway
version: 1.13
---

# Publishing Local Mode API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Omni Gateway running in Local Mode, you publish API instances using
[local declarative configuration files](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide). You specify the
location of these configuration files when you first run Omni Gateway.

For more information about how to run the gateway, see
[Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run).

Refer to these tutorials for examples on publishing APIs in Local Mode:

- [Publishing a Simple API Instance in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-publish-simple-api)

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-publish-api-multiple-services)

<!-- document id=fd19b3c6f9ff4a0aeb39f027e08887e3c185247581dac52bf58d6a470a8e26eb url=/mulesoft/current/en-us/gateway/latest/gateway-publish-apis-local.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Publishing Local Mode API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Omni Gateway running in Local Mode, you publish API instances using
[local declarative configuration files](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide). You specify the
location of these configuration files when you first run Omni Gateway.

For more information about how to run the gateway, see
[Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run).

Refer to these tutorials for examples on publishing APIs in Local Mode:

- [Publishing a Simple API Instance in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-simple-api)

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-api-multiple-services)

<!-- document id=8bf2cb52262f9f654611591b6ada39e483fe9bb56bcefd64df66fbe502610997 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-publish-apis-local.md -->

---
product: Omni Gateway
version: 1.9
---

# Publishing Local Mode APIs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Flex Gateway running in Local Mode, you publish APIs using
[local declarative configuration files](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide). You specify the
location of these configuration files when you first run Flex Gateway.

For more information about how to run the gateway, see
[Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run).

Refer to the following tutorials for examples on publishing APIs in Local Mode:

- [Publishing a Simple API in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-publish-simple-api)

- [Publishing an API with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-publish-api-multiple-services)

<!-- document id=eeb76d6165743e6f41b4d87b2ac5bece521b593760249f7997aef9c1e05bfc6b url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-publish-apis-conn.md -->

---
product: Omni Gateway
version: 1.12
---

# Publishing Managed Gateway and Connected Mode API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Flex Gateway or Flex Gateway running in Connected Mode, use **API Manager** to publish
API instances, Agents, LLMs, and MCP servers.

For more information, see:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool)

Additionally, you can publish a simple API instance with
[Getting Started with Managed Flex Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/1.12/flex-gateway-managed-getting-started) or
[Getting Started with Self-Managed Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started).

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

<!-- document id=1a91f70428f83f0cdcb5830188a013e11354ffaf7a4504ee9d6f5639b9b0c527 url=/mulesoft/current/en-us/gateway/1.13/gateway-publish-apis-conn.md -->

---
product: Omni Gateway
version: 1.13
---

# Publishing Managed Gateway and Connected Mode API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Omni Gateway or Omni Gateway running in Connected Mode, use **API Manager** to publish
API instances, Agents, LLMs, and MCP servers.

For more information, see:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool)

Additionally, you can publish a simple API instance with
[Getting Started with Managed Omni Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/1.13/gateway-managed-getting-started) or
[Getting Started with Self-Managed Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started).

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

<!-- document id=8021628dfadd9ce3de7d7b9522be8f6a12dfabe8d99fb00af5b953ea8ea88c62 url=/mulesoft/current/en-us/gateway/latest/gateway-publish-apis-conn.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Publishing Managed Gateway and Connected Mode API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Omni Gateway or Omni Gateway running in Connected Mode, use **API Manager** to publish
API instances, Agents, LLMs, and MCP servers.

For more information, see:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool)

Additionally, you can publish a simple API instance with
[Getting Started with Managed Omni Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/latest/gateway-managed-getting-started) or
[Getting Started with Self-Managed Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/gateway-getting-started).

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

<!-- document id=dd219f4b7b2eae012b9508023a69e775cf636c3bc3e584fdb4497be45a59dc01 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-publish-apis-conn.md -->

---
product: Omni Gateway
version: 1.9
---

# Publishing Managed Gateway and Connected Mode APIs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

For Managed Flex Gateway or Flex Gateway running in Connected Mode, use **API Manager** to publish
both API instances with a single upstream service, API instances with multiple upstream services,
MCP server instances, and A2A server instances.

For more information, see:

- [Adding an Omni Gateway API Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex)

- [Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool)

Additionally, you can publish a simple API with
[Getting Started with Managed Flex Gateway on CloudHub 2.0](https://docs.mulesoft.com/gateway/1.9/flex-gateway-managed-getting-started) or
[Getting Started with Self-Managed Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started).

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

<!-- document id=8ddc34a16a5bea4a5cdf974c6679cace423552cad141e858fa8e3f42d5e49fdc url=/mulesoft/current/en-us/gateway/1.13/agent-publish-apis.md -->

---
product: Omni Gateway
version: 1.13
---

# Publishing Omni Gateway Agent and Tool instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Similar to API instances, use **API Manager** to publish Agent, MCP, and LLM instances for Managed
Omni Gateway or Omni Gateway running in Connected Mode.

For more information, see
[Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool).

## See Also

- [Publishing Managed Gateway and Connected Mode API Instances](https://docs.mulesoft.com/gateway/1.13/gateway-publish-apis-conn)

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

<!-- document id=15b62ebccc97abbecbff4964cd0f743ac7da9e810c5b66dce0ef846bf21b14fa url=/mulesoft/current/en-us/gateway/latest/agent-publish-apis.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Publishing Omni Gateway Agent and Tool instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Similar to API instances, use **API Manager** to publish Agent, MCP, and LLM instances for Managed
Omni Gateway or Omni Gateway running in Connected Mode.

For more information, see
[Adding an Omni Gateway Agent or Tool Instance](https://docs.mulesoft.com/api-manager/latest/create-instance-task-agent-tool).

## See Also

- [Publishing Managed Gateway and Connected Mode API Instances](https://docs.mulesoft.com/gateway/latest/gateway-publish-apis-conn)

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

<!-- document id=c50311378c21e5d11d1fe6d65585e0fc9c9621730ddabafe3c22458fc513550f url=/mulesoft/current/en-us/gateway/1.13/gateway-publish-apis.md -->

---
product: Omni Gateway
version: 1.13
---

# Publishing Omni Gateway API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publishing an API instance consists of defining a client service and routing that service to a
backend location. Omni Gateway enables you to publish API instances via Anypoint Platform (Connected
Mode) or declarative configuration files (Local Mode).

To publish an API instance in Connected Mode, see
[Publishing Managed Gateway and Connected Mode API Instances](https://docs.mulesoft.com/gateway/1.13/gateway-publish-apis-conn).

To publish an API instance in Local Mode, see
[Publishing Local Mode API Instances](https://docs.mulesoft.com/gateway/1.13/gateway-publish-apis-local).

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

<!-- document id=935602c17bdb97c1349b8971bcca0650ae998232da56033b90919feb98eec1c6 url=/mulesoft/current/en-us/gateway/latest/gateway-publish-apis.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Publishing Omni Gateway API Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publishing an API instance consists of defining a client service and routing that service to a
backend location. Omni Gateway enables you to publish API instances via Anypoint Platform (Connected
Mode) or declarative configuration files (Local Mode).

To publish an API instance in Connected Mode, see
[Publishing Managed Gateway and Connected Mode API Instances](https://docs.mulesoft.com/gateway/latest/gateway-publish-apis-conn).

To publish an API instance in Local Mode, see
[Publishing Local Mode API Instances](https://docs.mulesoft.com/gateway/latest/gateway-publish-apis-local).

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

<!-- document id=850492fa030a6e39958e66b4bbe7f0c549f2eb8373a1928c96136f0088aba1e5 url=/mulesoft/current/en-us/gateway/1.12/policies-included-rate-limiting.md -->

---
product: Omni Gateway
version: 1.12
keywords: rate limiting, api gateway, flex gateway, gateway, policy
---

# Rate Limiting Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate Limiting</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a period of time</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>429 - Quota exceeded, requests are blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate Limiting policy enables you to control the incoming traffic to an API by limiting the
number of requests that the API can receive within a given period of time. After the limit is
reached, the policy rejects all requests, thereby avoiding any additional load on the backend API.

When you configure the Rate Limiting policy, you can specify any number of pairs of quota (number of
requests) and time window (time period) values.

> [!NOTE] A Rate Limiting policy applied to a Flex Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: rate-limiting-flex config: rateLimits: <array> // REQUIRED - maximumRequests:
<int> // REQUIRED timePeriodInMilliseconds: <int> // REQUIRED keySelector: <string> // OPTIONAL
exposeHeaders: <bool> // OPTIONAL, default: false clusterizable: <bool> // OPTIONAL, default: true

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>rateLimits</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>An map containing one or more rate limit specifications</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The quota number available per window</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The amount of time (a number) for which the quota is to be applied</p></div></div></td></tr><tr><td><div><div><p><code>keySelector</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>DataWeave expression selector key string that creates a group with independent counters for each value resolved by the expression.</p></div><div><p>For example, <code>#[attributes.queryParams['identifier']]</code> creates an independent counter group for requests containing an <code>identifier</code> query parameter.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>The boolean option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td></tr><tr><td><div><div><p><code>clusterizable</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Distributed: When using interconnected runtimes with this flag enabled, quota will be shared among all nodes</p></div></div></td></tr><tr><td><div><div><p>blockOnUnknownQuota</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>For policies using distributed rate limiting (<code>clusterizable</code>), block requests if the policy can’t retrieve the quota from shared storage. If <code>false</code> and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

\- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
clusterizable: false

The `#[attributes.method]` DataWeave expression creates one group for each available method in HTTP,
for example, the policy rate-limits GET requests independently of POST requests.

#### Distributed Rate Limit Resource Configuration Example

Distributed Rate Limit requires Shared Storage to be enabled. For more information about Shared
Storage, refer to
[Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
shared-storage-redis spec: sharedStorage: redis: address: redis:6379 user: user password: pass DB: 1

---

- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
  timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
  clusterizable: true

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Identifier</p></div></div></td><td><div><div><p>The selector key using a DataWeave or regular String</p></div></div></td><td><div><div><p><code>#[attributes.method]</code> creates one group for each available method in HTTP, for example, the policy rate-limits GET requests independently from POST requests.</p></div></div></td></tr><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The quota available per window</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The amount of time for which the quota is to be applied</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Unit</p></div></div></td><td><div><div><p>The time in milliseconds, seconds, minutes, or hours</p></div></div></td><td><div><div><p>Minutes</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When using interconnected runtimes with this flag enabled, quota will be shared among all nodes.</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>The option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Block on unknown quota</p></div></div></td><td><div><div><p>For policies using distributed rate limiting, block requests if the policy cannot retrieve the quota from shared storage. If not enabled and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

## How This Policy Works

The Rate Limiting policy monitors the number of requests made in the current window (the available
quota), allowing the requests to reach the backend only if the available quota is greater than zero.

You can configure the policy for multiple groups of requests by using identifiers in the policy
configuration. Each group has a separate available quota for its window.

To understand how the Rate Limiting policy works, consider an example in which the configuration of
3 requests every 10 seconds allows or restricts incoming requests, based on the quota available in
that window:

![A timeline of accepted and rejected requests in two time windows](/mulesoft/current/en-us/gateway/1.12/_images/rate-limiting-generic-example.png)

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed and the quota remaining is dropped after the window time has elapsed.

An accepted request passes through the API to the backend. Conversely, a rejected request displays
429 status for HTTP (or either 400 or 500 if the API is WSDL) and does not reach the backend.

A rejected request on the other hand, displays a “429 status for HTTP, ” (or either 400 or 500 if
the API is WSDL) and does not reach the backend.

## Examples

Consider the previously described configuration of 3 requests every 10 seconds and how it works when
the Rate Limiting policy is configured for clusters and uses identifiers.

### Configuring Identifiers by Using Regular Strings

When you use the UI to add identifiers to the policy configuration, you can define groups of
requests. The configured limits apply independently to each group. You can also use the identifier
`#[attributes.method]` for one bucket per HTTP method in your Rate Limiting policy configuration.

An `Identifier` in the UI is a non-obligatory parameter. By default, the `Identifier` has no value.
Based on whether you accept the default or provide a value, the policy performs in the following
ways:

- Not configured (default)

  The Rate Limiting quota applies to every request per bucket or group.

- Configured for an obligatory HTTP header

  Each header has its own quota. Header values are case-sensitive. Quotas are created using the
  _lazy creation_ strategy.

- Configured for a non-obligatory HTTP header

  Custom header, payload, query parameter, or expression values each have their own quotas.

  The identifier, if not sent in the request, defaults to an empty value, having its own quota. This
  behavior allows the Rate Limiting policy to be applied to an API consumed by uncontrolled clients,
  and at the same time accommodates special buckets for the clients sending the identifier.

The following example shows the order of events that occur over a period of time using the
identifier `#[attributes.method]` for a limit of 3 requests every 10 seconds:

![A line chart illustrating the acceptance and rejection of GET and POST requests over time](/mulesoft/current/en-us/gateway/1.12/_images/rate-limiting-configure-identifiers-example.png)

In the example:

- Every HTTP method is allowed 3 requests every 10 seconds (in this example, only GET and POST
  requests are made to the API).

- The Rate Limiting policy works in a fixed-window fashion.

  For more information, see the fixed-window size bracket in the diagram.

- The window start times are independent.

- The engine uses a _lazy creation_ strategy that spools a rate-limiting algorithm whenever the
  first request for a method is received.

### Configuring Identifiers by Using DataWeave Expressions

The rate-limiting engine, which is HTTP agnostic, depends solely on the resolution of the DataWeave
expression. You can alter the `Identifier` expression in the UI to cover complex rate-limiting
scenarios.

For example, you can configure a Rate Limiting policy with an identifier that uses one bucket for
all Class A and Class C LAN requests and another bucket for everything else. The following image
illustrates the second bucket in the previous sentence, which corresponds to 3 requests per 10
seconds quota with the DataWeave expression `#[attributes.queryParam[‘customIdentifier’]]` as the
policy identifier:

![A timeline that displays both accepted and rejected requests, organized by time intervals](/mulesoft/current/en-us/gateway/1.12/_images/rate-limiting-configure-identifiers-dataweave.png)

In the example:

- All requests without the identifier are resolved to the empty identifier and therefore use a
  single rate-limiting algorithm.

- Each different identifier uses a different bucket, each bucket with its own independent quota.

This configuration creates a false or a true bucket that corresponds to the locality of the IP that
made the request. The `false` and `true` values correspond to the domain of boolean values and not
HTTP.

Nevertheless, the policy works correctly because the engine treats the resolved expression as a
String. In this case, the value is automatically cast from Boolean to String. You can explicitly
define casting in DataWeave by adding `output text/plain ---` to your script.

> [!NOTE] The HTTP RFC header names are case-insensitive. Anypoint Connector for MuleSoft HTTP
> changes header names to lowercase characters. However, the DataWeave key is case-sensitive.
> Therefore, when creating the `Identifier` expression, remember to reference headers in lowercase.

### Configuring Unbound Identifier Sets

Every identifier result has one algorithm. You must carefully create a DataWeave expression that
does not return an unbound or a very large co-domain, which requires hosting the same number of
algorithms in memory (at least a request for every possible identifier has to be made, because
algorithms are created using the _lazy creation_ strategy).

For example, suppose the DataWeave expression uses the IP address as the identifier in a Flex
Gateway instance that is public to the internet. If every public IPv4 IP on the internet makes a
request to this instance, there will be 3,706,452,992 algorithms running in a single instance.

At an average of 250 bytes per algorithm, this amounts to approximately 1 terabyte in rate-limit
algorithms. Therefore, use a DataWeave expression that resolves to a finite number of identifier to
keep the resulting set as small as possible.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate Limiting policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and **Rate-Limiting SLA** policies for accountability and to enforce a hard limit
to a group (using the identifier in Rate Limiting) or to a client application (using **Rate-Limiting
SLA**). If you want to protect your backend, use the **Spike Control** policy instead.

<!-- document id=d8229770715ea358c07a1cb6d2b3e25da92e93d68673353065e4152a5e9636f3 url=/mulesoft/current/en-us/gateway/1.13/policies-included-rate-limiting.md -->

---
product: Omni Gateway
version: 1.13
keywords: rate limiting, api gateway, flex gateway, gateway, policy
---

# Rate Limiting Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate Limiting</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a period of time</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-release-notes">Rate Limiting</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>429 - Quota exceeded, requests are blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate Limiting policy enables you to control the incoming traffic to an API by limiting the
number of requests that the API can receive within a given period of time. After the limit is
reached, the policy rejects all requests, thereby avoiding any additional load on the backend API.

When you configure the Rate Limiting policy, you can specify any number of pairs of quota (number of
requests) and time window (time period) values.

> [!NOTE] A Rate Limiting policy applied to an Omni Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: rate-limiting-flex config: rateLimits: <array> // REQUIRED - maximumRequests:
<int> // REQUIRED timePeriodInMilliseconds: <int> // REQUIRED keySelector: <string> // OPTIONAL
exposeHeaders: <bool> // OPTIONAL, default: false clusterizable: <bool> // OPTIONAL, default: true

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>rateLimits</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>An map containing one or more rate limit specifications</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The quota number available per window</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The amount of time (a number) for which the quota is to be applied</p></div></div></td></tr><tr><td><div><div><p><code>keySelector</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>DataWeave expression selector key string that creates a group with independent counters for each value resolved by the expression.</p></div><div><p>For example, <code>#[attributes.queryParams['identifier']]</code> creates an independent counter group for requests containing an <code>identifier</code> query parameter.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>The boolean option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td></tr><tr><td><div><div><p><code>clusterizable</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Distributed: When using interconnected runtimes with this flag enabled, quota will be shared among all nodes</p></div></div></td></tr><tr><td><div><div><p>blockOnUnknownQuota</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>For policies using distributed rate limiting (<code>clusterizable</code>), block requests if the policy can’t retrieve the quota from shared storage. If <code>false</code> and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

\- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
clusterizable: false

The `#[attributes.method]` DataWeave expression creates one group for each available method in HTTP,
for example, the policy rate-limits GET requests independently of POST requests.

#### Distributed Rate Limit Resource Configuration Example

Distributed Rate Limit requires shared storage to be enabled. Configure either
[distributed shared storage](https://docs.mulesoft.com/gateway/1.13/conn-distributed-shared-storage-config) or
[Redis shared storage](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
shared-storage-redis spec: sharedStorage: redis: address: redis:6379 user: user password: pass DB: 1

---

- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
  timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
  clusterizable: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Identifier</p></div></div></td><td><div><div><p>The selector key using a DataWeave or regular String</p></div></div></td><td><div><div><p><code>#[attributes.method]</code> creates one group for each available method in HTTP, for example, the policy rate-limits GET requests independently from POST requests.</p></div></div></td></tr><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The quota available per window</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The amount of time for which the quota is to be applied</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Unit</p></div></div></td><td><div><div><p>The time in milliseconds, seconds, minutes, or hours</p></div></div></td><td><div><div><p>Minutes</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When using interconnected runtimes with this flag enabled, quota will be shared among all nodes.</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>The option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Block on unknown quota</p></div></div></td><td><div><div><p>For policies using distributed rate limiting, block requests if the policy cannot retrieve the quota from shared storage. If not enabled and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

## How This Policy Works

The Rate Limiting policy monitors the number of requests made in the current window (the available
quota), allowing the requests to reach the backend only if the available quota is greater than zero.

You can configure the policy for multiple groups of requests by using identifiers in the policy
configuration. Each group has a separate available quota for its window.

To understand how the Rate Limiting policy works, consider an example in which the configuration of
3 requests every 10 seconds allows or restricts incoming requests, based on the quota available in
that window:

![A timeline of accepted and rejected requests in two time windows](/mulesoft/current/en-us/gateway/1.13/_images/rate-limiting-generic-example.png)

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed and the quota remaining is dropped after the window time has elapsed.

An accepted request passes through the API to the backend. Conversely, a rejected request displays
429 status for HTTP (or either 400 or 500 if the API is WSDL) and does not reach the backend.

A rejected request on the other hand, displays a “429 status for HTTP, ” (or either 400 or 500 if
the API is WSDL) and does not reach the backend.

## Examples

Consider the previously described configuration of 3 requests every 10 seconds and how it works when
the Rate Limiting policy is configured for clusters and uses identifiers.

### Configuring Identifiers by Using Regular Strings

When you use the UI to add identifiers to the policy configuration, you can define groups of
requests. The configured limits apply independently to each group. You can also use the identifier
`#[attributes.method]` for one bucket per HTTP method in your Rate Limiting policy configuration.

An `Identifier` in the UI is a non-obligatory parameter. By default, the `Identifier` has no value.
Based on whether you accept the default or provide a value, the policy performs in the following
ways:

- Not configured (default)

  The Rate Limiting quota applies to every request per bucket or group.

- Configured for an obligatory HTTP header

  Each header has its own quota. Header values are case-sensitive. Quotas are created using the
  _lazy creation_ strategy.

- Configured for a non-obligatory HTTP header

  Custom header, payload, query parameter, or expression values each have their own quotas.

  The identifier, if not sent in the request, defaults to an empty value, having its own quota. This
  behavior allows the Rate Limiting policy to be applied to an API consumed by uncontrolled clients,
  and at the same time accommodates special buckets for the clients sending the identifier.

The following example shows the order of events that occur over a period of time using the
identifier `#[attributes.method]` for a limit of 3 requests every 10 seconds:

![A line chart illustrating the acceptance and rejection of GET and POST requests over time](/mulesoft/current/en-us/gateway/1.13/_images/rate-limiting-configure-identifiers-example.png)

In the example:

- Every HTTP method is allowed 3 requests every 10 seconds (in this example, only GET and POST
  requests are made to the API).

- The Rate Limiting policy works in a fixed-window fashion.

  For more information, see the fixed-window size bracket in the diagram.

- The window start times are independent.

- The engine uses a _lazy creation_ strategy that spools a rate-limiting algorithm whenever the
  first request for a method is received.

### Configuring Identifiers by Using DataWeave Expressions

The rate-limiting engine, which is HTTP agnostic, depends solely on the resolution of the DataWeave
expression. You can alter the `Identifier` expression in the UI to cover complex rate-limiting
scenarios.

For example, you can configure a Rate Limiting policy with an identifier that uses one bucket for
all Class A and Class C LAN requests and another bucket for everything else. The following image
illustrates the second bucket in the previous sentence, which corresponds to 3 requests per 10
seconds quota with the DataWeave expression `#[attributes.queryParam[‘customIdentifier’]]` as the
policy identifier:

![A timeline that displays both accepted and rejected requests, organized by time intervals](/mulesoft/current/en-us/gateway/1.13/_images/rate-limiting-configure-identifiers-dataweave.png)

In the example:

- All requests without the identifier are resolved to the empty identifier and therefore use a
  single rate-limiting algorithm.

- Each different identifier uses a different bucket, each bucket with its own independent quota.

This configuration creates a false or a true bucket that corresponds to the locality of the IP that
made the request. The `false` and `true` values correspond to the domain of boolean values and not
HTTP.

Nevertheless, the policy works correctly because the engine treats the resolved expression as a
String. In this case, the value is automatically cast from Boolean to String. You can explicitly
define casting in DataWeave by adding `output text/plain ---` to your script.

> [!NOTE] The HTTP RFC header names are case-insensitive. Anypoint Connector for MuleSoft HTTP
> changes header names to lowercase characters. However, the DataWeave key is case-sensitive.
> Therefore, when creating the `Identifier` expression, remember to reference headers in lowercase.

### Configuring Unbound Identifier Sets

Every identifier result has one algorithm. You must carefully create a DataWeave expression that
does not return an unbound or a very large co-domain, which requires hosting the same number of
algorithms in memory (at least a request for every possible identifier has to be made, because
algorithms are created using the _lazy creation_ strategy).

For example, suppose the DataWeave expression uses the IP address as the identifier in an Omni
Gateway instance that is public to the internet. If every public IPv4 IP on the internet makes a
request to this instance, there will be 3,706,452,992 algorithms running in a single instance.

At an average of 250 bytes per algorithm, this amounts to approximately 1 terabyte in rate-limit
algorithms. Therefore, use a DataWeave expression that resolves to a finite number of identifier to
keep the resulting set as small as possible.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate Limiting policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and **Rate-Limiting SLA** policies for accountability and to enforce a hard limit
to a group (using the identifier in Rate Limiting) or to a client application (using **Rate-Limiting
SLA**). If you want to protect your backend, use the **Spike Control** policy instead.

<!-- document id=17fec61dd4922f6dca8b2d60df35a0675a2ff149231a87d087d5385c7e4938ee url=/mulesoft/current/en-us/gateway/1.9/policies-included-rate-limiting.md -->

---
product: Omni Gateway
version: 1.9
keywords: rate limiting, api gateway, flex gateway, gateway, policy
---

# Rate Limiting Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate Limiting</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a period of time</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>429 - Quota exceeded, requests are blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate Limiting policy enables you to control the incoming traffic to an API by limiting the
number of requests that the API can receive within a given period of time. After the limit is
reached, the policy rejects all requests, thereby avoiding any additional load on the backend API.

When you configure the Rate Limiting policy, you can specify any number of pairs of quota (number of
requests) and time window (time period) values.

> [!NOTE] A Rate Limiting policy applied to a Flex Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: rate-limiting-flex config: rateLimits: <array> // REQUIRED - maximumRequests:
<int> // REQUIRED timePeriodInMilliseconds: <int> // REQUIRED keySelector: <string> // OPTIONAL
exposeHeaders: <bool> // OPTIONAL, default: false clusterizable: <bool> // OPTIONAL, default: true

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>rateLimits</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>An map containing one or more rate limit specifications</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The quota number available per window</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The amount of time (a number) for which the quota is to be applied</p></div></div></td></tr><tr><td><div><div><p><code>keySelector</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>DataWeave expression selector key string that creates a group with independent counters for each value resolved by the expression.</p></div><div><p>For example, <code>#[attributes.queryParams['identifier']]</code> creates an independent counter group for requests containing an <code>identifier</code> query parameter.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>The boolean option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td></tr><tr><td><div><div><p><code>clusterizable</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Distributed: When using interconnected runtimes with this flag enabled, quota will be shared among all nodes</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

\- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
clusterizable: false

The `#[attributes.method]` DataWeave expression creates one group for each available method in HTTP,
for example, the policy rate-limits GET requests independently of POST requests.

#### Distributed Rate Limit Resource Configuration Example

Distributed Rate Limit requires Shared Storage to be enabled. For more information about Shared
Storage, refer to
[Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
shared-storage-redis spec: sharedStorage: redis: address: redis:6379 user: user password: pass DB: 1

---

- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
  timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
  clusterizable: true

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Identifier</p></div></div></td><td><div><div><p>The selector key using a DataWeave or regular String</p></div></div></td><td><div><div><p><code>#[attributes.method]</code> creates one group for each available method in HTTP, for example, the policy rate-limits GET requests independently from POST requests.</p></div></div></td></tr><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The quota available per window</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The amount of time for which the quota is to be applied</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Unit</p></div></div></td><td><div><div><p>The time in milliseconds, seconds, minutes, or hours</p></div></div></td><td><div><div><p>Minutes</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When using interconnected runtimes with this flag enabled, quota will be shared among all nodes.</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>The option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr></tbody></table>

## How This Policy Works

The Rate Limiting policy monitors the number of requests made in the current window (the available
quota), allowing the requests to reach the backend only if the available quota is greater than zero.

You can configure the policy for multiple groups of requests by using identifiers in the policy
configuration. Each group has a separate available quota for its window.

To understand how the Rate Limiting policy works, consider an example in which the configuration of
3 requests every 10 seconds allows or restricts incoming requests, based on the quota available in
that window:

![A timeline of accepted and rejected requests in two time windows](/mulesoft/current/en-us/gateway/1.9/_images/rate-limiting-generic-example.png)

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed and the quota remaining is dropped after the window time has elapsed.

An accepted request passes through the API to the backend. Conversely, a rejected request displays
429 status for HTTP (or either 400 or 500 if the API is WSDL) and does not reach the backend.

A rejected request on the other hand, displays a “429 status for HTTP, ” (or either 400 or 500 if
the API is WSDL) and does not reach the backend.

## Examples

Consider the previously described configuration of 3 requests every 10 seconds and how it works when
the Rate Limiting policy is configured for clusters and uses identifiers.

### Configuring Identifiers by Using Regular Strings

When you use the UI to add identifiers to the policy configuration, you can define groups of
requests. The configured limits apply independently to each group. You can also use the identifier
`#[attributes.method]` for one bucket per HTTP method in your Rate Limiting policy configuration.

An `Identifier` in the UI is a non-obligatory parameter. By default, the `Identifier` has no value.
Based on whether you accept the default or provide a value, the policy performs in the following
ways:

- Not configured (default)

  The Rate Limiting quota applies to every request per bucket or group.

- Configured for an obligatory HTTP header

  Each header has its own quota. Header values are case-sensitive. Quotas are created using the
  _lazy creation_ strategy.

- Configured for a non-obligatory HTTP header

  Custom header, payload, query parameter, or expression values each have their own quotas.

  The identifier, if not sent in the request, defaults to an empty value, having its own quota. This
  behavior allows the Rate Limiting policy to be applied to an API consumed by uncontrolled clients,
  and at the same time accommodates special buckets for the clients sending the identifier.

The following example shows the order of events that occur over a period of time using the
identifier `#[attributes.method]` for a limit of 3 requests every 10 seconds:

![A line chart illustrating the acceptance and rejection of GET and POST requests over time](/mulesoft/current/en-us/gateway/1.9/_images/rate-limiting-configure-identifiers-example.png)

In the example:

- Every HTTP method is allowed 3 requests every 10 seconds (in this example, only GET and POST
  requests are made to the API).

- The Rate Limiting policy works in a fixed-window fashion.

  For more information, see the fixed-window size bracket in the diagram.

- The window start times are independent.

- The engine uses a _lazy creation_ strategy that spools a rate-limiting algorithm whenever the
  first request for a method is received.

### Configuring Identifiers by Using DataWeave Expressions

The rate-limiting engine, which is HTTP agnostic, depends solely on the resolution of the DataWeave
expression. You can alter the `Identifier` expression in the UI to cover complex rate-limiting
scenarios.

For example, you can configure a Rate Limiting policy with an identifier that uses one bucket for
all Class A and Class C LAN requests and another bucket for everything else. The following image
illustrates the second bucket in the previous sentence, which corresponds to 3 requests per 10
seconds quota with the DataWeave expression `#[attributes.queryParam[‘customIdentifier’]]` as the
policy identifier:

![A timeline that displays both accepted and rejected requests, organized by time intervals](/mulesoft/current/en-us/gateway/1.9/_images/rate-limiting-configure-identifiers-dataweave.png)

In the example:

- All requests without the identifier are resolved to the empty identifier and therefore use a
  single rate-limiting algorithm.

- Each different identifier uses a different bucket, each bucket with its own independent quota.

This configuration creates a false or a true bucket that corresponds to the locality of the IP that
made the request. The `false` and `true` values correspond to the domain of boolean values and not
HTTP.

Nevertheless, the policy works correctly because the engine treats the resolved expression as a
String. In this case, the value is automatically cast from Boolean to String. You can explicitly
define casting in DataWeave by adding `output text/plain ---` to your script.

> [!NOTE] The HTTP RFC header names are case-insensitive. Anypoint Connector for MuleSoft HTTP
> changes header names to lowercase characters. However, the DataWeave key is case-sensitive.
> Therefore, when creating the `Identifier` expression, remember to reference headers in lowercase.

### Configuring Unbound Identifier Sets

Every identifier result has one algorithm. You must carefully create a DataWeave expression that
does not return an unbound or a very large co-domain, which requires hosting the same number of
algorithms in memory (at least a request for every possible identifier has to be made, because
algorithms are created using the _lazy creation_ strategy).

For example, suppose the DataWeave expression uses the IP address as the identifier in a Flex
Gateway instance that is public to the internet. If every public IPv4 IP on the internet makes a
request to this instance, there will be 3,706,452,992 algorithms running in a single instance.

At an average of 250 bytes per algorithm, this amounts to approximately 1 terabyte in rate-limit
algorithms. Therefore, use a DataWeave expression that resolves to a finite number of identifier to
keep the resulting set as small as possible.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate Limiting policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and **Rate-Limiting SLA** policies for accountability and to enforce a hard limit
to a group (using the identifier in Rate Limiting) or to a client application (using **Rate-Limiting
SLA**). If you want to protect your backend, use the **Spike Control** policy instead.

<!-- document id=91504ce3a75b7b5a387db5a78f4ba943129a380de6a78ae544bca7428b95fb5f url=/mulesoft/current/en-us/gateway/latest/policies-included-rate-limiting.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: rate limiting, api gateway, flex gateway, gateway, policy
---

# Rate Limiting Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate Limiting</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a period of time</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-release-notes">Rate Limiting</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>429 - Quota exceeded, requests are blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate Limiting policy enables you to control the incoming traffic to an API by limiting the
number of requests that the API can receive within a given period of time. After the limit is
reached, the policy rejects all requests, thereby avoiding any additional load on the backend API.

When you configure the Rate Limiting policy, you can specify any number of pairs of quota (number of
requests) and time window (time period) values.

> [!NOTE] A Rate Limiting policy applied to an Omni Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: rate-limiting-flex config: rateLimits: <array> // REQUIRED - maximumRequests:
<int> // REQUIRED timePeriodInMilliseconds: <int> // REQUIRED keySelector: <string> // OPTIONAL
exposeHeaders: <bool> // OPTIONAL, default: false clusterizable: <bool> // OPTIONAL, default: true

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>rateLimits</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>An map containing one or more rate limit specifications</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The quota number available per window</p></div></div></td></tr><tr><td><div><div><p><code>rateLimits.timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The amount of time (a number) for which the quota is to be applied</p></div></div></td></tr><tr><td><div><div><p><code>keySelector</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>DataWeave expression selector key string that creates a group with independent counters for each value resolved by the expression.</p></div><div><p>For example, <code>#[attributes.queryParams['identifier']]</code> creates an independent counter group for requests containing an <code>identifier</code> query parameter.</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>The boolean option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td></tr><tr><td><div><div><p><code>clusterizable</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Distributed: When enabled, the quota is shared among all Omni Gateway replicas. Distributed rate limiting requires shared storage to be enabled.</p></div></div></td></tr><tr><td><div><div><p>blockOnUnknownQuota</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>For policies using distributed rate limiting (<code>clusterizable</code>), block requests if the policy can’t retrieve the quota from shared storage. If <code>false</code> and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

#### Resource Configuration Example

The following example defines a rate limit of three requests every six seconds:

\- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
clusterizable: false

The `#[attributes.method]` DataWeave expression creates one group for each available method in HTTP,
for example, the policy rate-limits GET requests independently of POST requests.

#### Distributed Rate Limit Resource Configuration Example

Distributed Rate Limit requires shared storage to be enabled. Configure either
[distributed shared storage](https://docs.mulesoft.com/gateway/latest/conn-distributed-shared-storage-config) or
[Redis shared storage](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
shared-storage-redis spec: sharedStorage: redis: address: redis:6379 user: user password: pass DB: 1

---

- policyRef: name: rate-limiting-flex config: rateLimits: - maximumRequests: 3
  timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.method\]" exposeHeaders: true
  clusterizable: true

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Identifier</p></div></div></td><td><div><div><p>The selector key using a DataWeave or regular String</p></div></div></td><td><div><div><p><code>#[attributes.method]</code> creates one group for each available method in HTTP, for example, the policy rate-limits GET requests independently from POST requests.</p></div></div></td></tr><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The quota available per window</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The amount of time for which the quota is to be applied</p></div></div></td><td><div><div><p>A positive number</p></div></div></td></tr><tr><td><div><div><p>Time Unit</p></div></div></td><td><div><div><p>The time in milliseconds, seconds, minutes, or hours</p></div></div></td><td><div><div><p>Minutes</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the quota is shared among all Omni Gateway replicas. Distributed rate limiting requires shared storage to be enabled.</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>The option that defines whether to expose the <a href="#response-header">x-ratelimit headers</a> as part of the response</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Block on unknown quota</p></div></div></td><td><div><div><p>For policies using distributed rate limiting, block requests if the policy cannot retrieve the quota from shared storage. If not enabled and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td><td><div><div><p>checked or unchecked</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

## How This Policy Works

The Rate Limiting policy monitors the number of requests made in the current window (the available
quota), allowing the requests to reach the backend only if the available quota is greater than zero.

You can configure the policy for multiple groups of requests by using identifiers in the policy
configuration. Each group has a separate available quota for its window.

To understand how the Rate Limiting policy works, consider an example in which the configuration of
3 requests every 10 seconds allows or restricts incoming requests, based on the quota available in
that window:

![A timeline of accepted and rejected requests in two time windows](/mulesoft/current/en-us/gateway/latest/_images/rate-limiting-generic-example.png)

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed and the quota remaining is dropped after the window time has elapsed.

An accepted request passes through the API to the backend. Conversely, a rejected request displays
429 status for HTTP (or either 400 or 500 if the API is WSDL) and does not reach the backend.

A rejected request on the other hand, displays a “429 status for HTTP, ” (or either 400 or 500 if
the API is WSDL) and does not reach the backend.

## Examples

Consider the previously described configuration of 3 requests every 10 seconds and how it works when
the Rate Limiting policy is configured for clusters and uses identifiers.

### Configuring Identifiers by Using Regular Strings

When you use the UI to add identifiers to the policy configuration, you can define groups of
requests. The configured limits apply independently to each group. You can also use the identifier
`#[attributes.method]` for one bucket per HTTP method in your Rate Limiting policy configuration.

An `Identifier` in the UI is a non-obligatory parameter. By default, the `Identifier` has no value.
Based on whether you accept the default or provide a value, the policy performs in the following
ways:

- Not configured (default)

  The Rate Limiting quota applies to every request per bucket or group.

- Configured for an obligatory HTTP header

  Each header has its own quota. Header values are case-sensitive. Quotas are created using the
  _lazy creation_ strategy.

- Configured for a non-obligatory HTTP header

  Custom header, payload, query parameter, or expression values each have their own quotas.

  The identifier, if not sent in the request, defaults to an empty value, having its own quota. This
  behavior allows the Rate Limiting policy to be applied to an API consumed by uncontrolled clients,
  and at the same time accommodates special buckets for the clients sending the identifier.

The following example shows the order of events that occur over a period of time using the
identifier `#[attributes.method]` for a limit of 3 requests every 10 seconds:

![A line chart illustrating the acceptance and rejection of GET and POST requests over time](/mulesoft/current/en-us/gateway/latest/_images/rate-limiting-configure-identifiers-example.png)

In the example:

- Every HTTP method is allowed 3 requests every 10 seconds (in this example, only GET and POST
  requests are made to the API).

- The Rate Limiting policy works in a fixed-window fashion.

  For more information, see the fixed-window size bracket in the diagram.

- The window start times are independent.

- The engine uses a _lazy creation_ strategy that spools a rate-limiting algorithm whenever the
  first request for a method is received.

### Configuring Identifiers by Using DataWeave Expressions

The rate-limiting engine, which is HTTP agnostic, depends solely on the resolution of the DataWeave
expression. You can alter the `Identifier` expression in the UI to cover complex rate-limiting
scenarios.

For example, you can configure a Rate Limiting policy with an identifier that uses one bucket for
all Class A and Class C LAN requests and another bucket for everything else. The following image
illustrates the second bucket in the previous sentence, which corresponds to 3 requests per 10
seconds quota with the DataWeave expression `#[attributes.queryParam[‘customIdentifier’]]` as the
policy identifier:

![A timeline that displays both accepted and rejected requests, organized by time intervals](/mulesoft/current/en-us/gateway/latest/_images/rate-limiting-configure-identifiers-dataweave.png)

In the example:

- All requests without the identifier are resolved to the empty identifier and therefore use a
  single rate-limiting algorithm.

- Each different identifier uses a different bucket, each bucket with its own independent quota.

This configuration creates a false or a true bucket that corresponds to the locality of the IP that
made the request. The `false` and `true` values correspond to the domain of boolean values and not
HTTP.

Nevertheless, the policy works correctly because the engine treats the resolved expression as a
String. In this case, the value is automatically cast from Boolean to String. You can explicitly
define casting in DataWeave by adding `output text/plain ---` to your script.

> [!NOTE] The HTTP RFC header names are case-insensitive. Anypoint Connector for MuleSoft HTTP
> changes header names to lowercase characters. However, the DataWeave key is case-sensitive.
> Therefore, when creating the `Identifier` expression, remember to reference headers in lowercase.

### Configuring Unbound Identifier Sets

Every identifier result has one algorithm. You must carefully create a DataWeave expression that
does not return an unbound or a very large co-domain, which requires hosting the same number of
algorithms in memory (at least a request for every possible identifier has to be made, because
algorithms are created using the _lazy creation_ strategy).

For example, suppose the DataWeave expression uses the IP address as the identifier in an Omni
Gateway instance that is public to the internet. If every public IPv4 IP on the internet makes a
request to this instance, there will be 3,706,452,992 algorithms running in a single instance.

At an average of 250 bytes per algorithm, this amounts to approximately 1 terabyte in rate-limit
algorithms. Therefore, use a DataWeave expression that resolves to a finite number of identifier to
keep the resulting set as small as possible.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate Limiting policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and **Rate-Limiting SLA** policies for accountability and to enforce a hard limit
to a group (using the identifier in Rate Limiting) or to a client application (using **Rate-Limiting
SLA**). If you want to protect your backend, use the **Spike Control** policy instead.

<!-- document id=8cba4f9cd2b77e13bd716968c8ee2ce965529f2f5af5d8f1c2df59e6be5a0b15 url=/mulesoft/current/en-us/gateway/1.12/policies-included-rate-limiting-sla.md -->

---
product: Omni Gateway
version: 1.12
keywords: rate-limiting sla, api gateway, flex gateway, gateway, policy
---

# Rate Limiting: SLA-Based Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate-limiting SLA</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>401 - Request blocked due to invalid client credentials (client ID or client secret) provided</p></div></div></td></tr><tr><td><div><div><p>429 - Quota exceeded; requests blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate-Limiting Service Level Agreement (SLA) policy enables you to control incoming traffic to an
API by limiting the number of requests that the API can receive within a given timespan. When the
limit is reached before the time expires, the policy rejects all requests, thereby avoiding any
additional load on the backend API.

To apply the Rate-Limiting SLA policy to an API, you must first create a contract between the API
and a registered client application. The number of requests that an API can receive within a given
time is defined in the [contracts](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task) section
in API Manager.

Each request must be identified by a client ID and an optional client secret (depending on the
policy configuration). To review how to obtain the client credentials of a registered client
application, see
[Obtaining Client Credentials of a Registered Application](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task).

> [!NOTE] A Rate-Limiting SLA policy applied to a Flex Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The Rate-Limiting SLA policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client Application’s ID for a Contract of the API</p></div></div></td><td><div><div><p>Only one rate-limiting algorithm is created per ID: <code>#[attributes.headers['client_id']]</code> This example looks for an HTTP header called ‘client_id’ and uses its value.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client application’s client secret for a contract of the API</p></div></div></td><td><div><div><p>This is an optional value. Example: <code>#[attributes.headers['client_secret']]</code></p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the quota is shared among Flex Replicas</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Defines whether to expose the <a href="#response-header">x-ratelimit headers,</a> as part of the response</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Block on unknown quota</p></div></div></td><td><div><div><p>For policies using distributed rate limiting, block requests if the policy can’t retrieve the quota from shared storage. If not enabled and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

## Enable Shared Storage

Distributed Rate-Limiting requires Shared Storage to be enabled. For more information about Shared
Storage, refer to
[Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config).

## How This Policy Works

The Rate-Limiting SLA policy monitors the number of requests made in the current window (the
available quota), allowing the requests to reach the backend only if the available quota is greater
than zero.

Because each client defines a separate available quota for their window, the client application must
define an SLA with the API (a contract). Therefore, to verify whether the request is within the SLA
limit, you must define a way to obtain the client ID from the request, and optionally the client
Secret.

After a contract is created between a client application and an API, API gateway automatically
manages these contracts by monitoring your API Manager configurations. Additionally, API gateway
implements high-availability strategies in case of unexpected downtime in the Anypoint Platform
management plane.

To understand how the Rate-Limiting SLA policy works, consider an example in which the configuration
of an SLA of 3 requests every 10 seconds for the client with ID “ID#1” allows or restricts the
request, based on the quota available in that window:

![A timeline chart that displays both accepted and rejected client requests within a specified window](/mulesoft/current/en-us/gateway/1.12/_images/rate-limiting-sla-general.png)

In the example:

- Requests of client with ID “ID#1”:

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed. Because the time elapses in this window, the remaining quota is unused.

An accepted request passes through the API to the backend. Conversely, a rejected request displays a
`429 status for HTTP` (or 400, or 500 if the API is WSDL) and does not reach the backend.

- Requests of Client with ID “ID#2”:

Because the client has no contract defined for the API, every request is rejected , and therefore no
request is allowed.

An API might have several contracts, each with its own SLA. The Rate-Limiting SLA policy
independently monitors the quota (and windows) available for each client by creating one
rate-limiting algorithm per contract. With the first request to the API, algorithms are created
using the _lazy creation_ strategy.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate-Limiting SLA policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits within an SLA ?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

> [!NOTE] When on distributed mode, the X-Ratelimit-Remaining header is not perfectly synchronized
> with all the replicas. With multiple replicas on distributed mode, the X-Ratelimit-Remaining
> header is an estimation of how much quota the replica has available for itself. It does not
> represent the actual value of the remaining quota available for the API.
>
> The following describes a valid scenario:
>
> - Created a SLA tier name "Titanium" having rate limit of "999999999 req per 10 min"
>
> - Sent 1 request to replica 1 → x-ratelimit-remaining : 999999998
>
> - Sent 1 request to replica 2 → x-ratelimit-remaining : 899999998
>
> This does not mean that the quota will be surpassed.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=8d39f3f0ab93ba35b1568c096adc14eaf3cab40f704a60aa851c068fb392749e url=/mulesoft/current/en-us/gateway/1.13/policies-included-rate-limiting-sla.md -->

---
product: Omni Gateway
version: 1.13
keywords: rate-limiting sla, api gateway, flex gateway, gateway, policy
---

# Rate Limiting: SLA-Based Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate-limiting SLA</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-sla-release-notes">Rate-limiting SLA</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>401 - Request blocked due to invalid client credentials (client ID or client secret) provided</p></div></div></td></tr><tr><td><div><div><p>429 - Quota exceeded; requests blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate-Limiting Service Level Agreement (SLA) policy enables you to control incoming traffic to an
API by limiting the number of requests that the API can receive within a given timespan. When the
limit is reached before the time expires, the policy rejects all requests, thereby avoiding any
additional load on the backend API.

To apply the Rate-Limiting SLA policy to an API, you must first create a contract between the API
and a registered client application. The number of requests that an API can receive within a given
time is defined in the [contracts](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task) section
in API Manager.

Each request must be identified by a client ID and an optional client secret (depending on the
policy configuration). To review how to obtain the client credentials of a registered client
application, see
[Obtaining Client Credentials of a Registered Application](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task).

> [!NOTE] A Rate-Limiting SLA policy applied to an Omni Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Rate-Limiting SLA policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client Application’s ID for a Contract of the API</p></div></div></td><td><div><div><p>Only one rate-limiting algorithm is created per ID: <code>#[attributes.headers['client_id']]</code> This example looks for an HTTP header called ‘client_id’ and uses its value.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client application’s client secret for a contract of the API</p></div></div></td><td><div><div><p>This is an optional value. Example: <code>#[attributes.headers['client_secret']]</code></p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the quota is shared among Omni Replicas</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Defines whether to expose the <a href="#response-header">x-ratelimit headers,</a> as part of the response</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Block on unknown quota</p></div></div></td><td><div><div><p>For policies using distributed rate limiting, block requests if the policy can’t retrieve the quota from shared storage. If not enabled and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

## Enable Shared Storage

Distributed Rate-Limiting requires Shared Storage to be enabled. For more information about Shared
Storage, refer to
[Configuring Redis Shared Storage for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config).

## How This Policy Works

The Rate-Limiting SLA policy monitors the number of requests made in the current window (the
available quota), allowing the requests to reach the backend only if the available quota is greater
than zero.

Because each client defines a separate available quota for their window, the client application must
define an SLA with the API (a contract). Therefore, to verify whether the request is within the SLA
limit, you must define a way to obtain the client ID from the request, and optionally the client
Secret.

After a contract is created between a client application and an API, API gateway automatically
manages these contracts by monitoring your API Manager configurations. Additionally, API gateway
implements high-availability strategies in case of unexpected downtime in the Anypoint Platform
management plane.

To understand how the Rate-Limiting SLA policy works, consider an example in which the configuration
of an SLA of 3 requests every 10 seconds for the client with ID “ID#1” allows or restricts the
request, based on the quota available in that window:

![A timeline chart that displays both accepted and rejected client requests within a specified window](/mulesoft/current/en-us/gateway/1.13/_images/rate-limiting-sla-general.png)

In the example:

- Requests of client with ID “ID#1”:

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed. Because the time elapses in this window, the remaining quota is unused.

An accepted request passes through the API to the backend. Conversely, a rejected request displays a
`429 status for HTTP` (or 400, or 500 if the API is WSDL) and does not reach the backend.

- Requests of Client with ID “ID#2”:

Because the client has no contract defined for the API, every request is rejected , and therefore no
request is allowed.

An API might have several contracts, each with its own SLA. The Rate-Limiting SLA policy
independently monitors the quota (and windows) available for each client by creating one
rate-limiting algorithm per contract. With the first request to the API, algorithms are created
using the _lazy creation_ strategy.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate-Limiting SLA policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits within an SLA ?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

> [!NOTE] When on distributed mode, the X-Ratelimit-Remaining header is not perfectly synchronized
> with all the replicas. With multiple replicas on distributed mode, the X-Ratelimit-Remaining
> header is an estimation of how much quota the replica has available for itself. It does not
> represent the actual value of the remaining quota available for the API.
>
> The following describes a valid scenario:
>
> - Created a SLA tier name "Titanium" having rate limit of "999999999 req per 10 min"
>
> - Sent 1 request to replica 1 → x-ratelimit-remaining : 999999998
>
> - Sent 1 request to replica 2 → x-ratelimit-remaining : 899999998
>
> This does not mean that the quota will be surpassed.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=5204b19f37ea5165c008ab6d27ef3942592d3922e56bd2ec87eff15e1e7aae05 url=/mulesoft/current/en-us/gateway/1.9/policies-included-rate-limiting-sla.md -->

---
product: Omni Gateway
version: 1.9
keywords: rate-limiting sla, api gateway, flex gateway, gateway, policy
---

# Rate Limiting: SLA-Based Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate-limiting SLA</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>401 - Request blocked due to invalid client credentials (client ID or client secret) provided</p></div></div></td></tr><tr><td><div><div><p>429 - Quota exceeded; requests blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate-Limiting Service Level Agreement (SLA) policy enables you to control incoming traffic to an
API by limiting the number of requests that the API can receive within a given timespan. When the
limit is reached before the time expires, the policy rejects all requests, thereby avoiding any
additional load on the backend API.

To apply the Rate-Limiting SLA policy to an API, you must first create a contract between the API
and a registered client application. The number of requests that an API can receive within a given
time is defined in the [contracts](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task) section
in API Manager.

Each request must be identified by a client ID and an optional client secret (depending on the
policy configuration). To review how to obtain the client credentials of a registered client
application, see
[Obtaining Client Credentials of a Registered Application](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task).

> [!NOTE] A Rate-Limiting SLA policy applied to a Flex Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Flex Gateway Local Mode

The Rate-Limiting SLA policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client Application’s ID for a Contract of the API</p></div></div></td><td><div><div><p>Only one rate-limiting algorithm is created per ID: <code>#[attributes.headers['client_id']]</code> This example looks for an HTTP header called ‘client_id’ and uses its value.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client application’s client secret for a contract of the API</p></div></div></td><td><div><div><p>This is an optional value. Example: <code>#[attributes.headers['client_secret']]</code></p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the quota is shared among Flex Replicas</p></div></div></td><td><div><div><p>Checked or Unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Defines whether to expose the <a href="#response-header">x-ratelimit headers,</a> as part of the response</p></div></div></td><td><div><div><p>Checked or Unchecked</p></div></div></td></tr></tbody></table>

## Enable Shared Storage

Distributed Rate-Limiting requires Shared Storage to be enabled. For more information about Shared
Storage, refer to
[Configuring Shared Storage for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config).

## How This Policy Works

The Rate-Limiting SLA policy monitors the number of requests made in the current window (the
available quota), allowing the requests to reach the backend only if the available quota is greater
than zero.

Because each client defines a separate available quota for their window, the client application must
define an SLA with the API (a contract). Therefore, to verify whether the request is within the SLA
limit, you must define a way to obtain the client ID from the request, and optionally the client
Secret.

After a contract is created between a client application and an API, API gateway automatically
manages these contracts by monitoring your API Manager configurations. Additionally, API gateway
implements high-availability strategies in case of unexpected downtime in the Anypoint Platform
management plane.

To understand how the Rate-Limiting SLA policy works, consider an example in which the configuration
of an SLA of 3 requests every 10 seconds for the client with ID “ID#1” allows or restricts the
request, based on the quota available in that window:

![A timeline chart that displays both accepted and rejected client requests within a specified window](/mulesoft/current/en-us/gateway/1.9/_images/rate-limiting-sla-general.png)

In the example:

- Requests of client with ID “ID#1”:

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed. Because the time elapses in this window, the remaining quota is unused.

An accepted request passes through the API to the backend. Conversely, a rejected request displays a
`429 status for HTTP` (or 400, or 500 if the API is WSDL) and does not reach the backend.

- Requests of Client with ID “ID#2”:

Because the client has no contract defined for the API, every request is rejected , and therefore no
request is allowed.

An API might have several contracts, each with its own SLA. The Rate-Limiting SLA policy
independently monitors the quota (and windows) available for each client by creating one
rate-limiting algorithm per contract. With the first request to the API, algorithms are created
using the _lazy creation_ strategy.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate-Limiting SLA policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits within an SLA ?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

> [!NOTE] When on distributed mode, the X-Ratelimit-Remaining header is not perfectly synchronized
> with all the replicas. With multiple replicas on distributed mode, the X-Ratelimit-Remaining
> header is an estimation of how much quota the replica has available for itself. It does not
> represent the actual value of the remaining quota available for the API.
>
> The following describes a valid scenario:
>
> - Created a SLA tier name "Titanium" having rate limit of "999999999 req per 10 min"
>
> - Sent 1 request to replica 1 → x-ratelimit-remaining : 999999998
>
> - Sent 1 request to replica 2 → x-ratelimit-remaining : 899999998
>
> This does not mean that the quota will be surpassed.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=5e5be3bd1512f966a7c9c641919f487eb7aedaf649c882d5bee3d799d74910e8 url=/mulesoft/current/en-us/gateway/latest/policies-included-rate-limiting-sla.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: rate-limiting sla, api gateway, flex gateway, gateway, policy
---

# Rate Limiting: SLA-Based Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Rate-limiting SLA</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Monitors access to an API by defining the maximum number of requests processed within a timespan, based on SLAs</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.2.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/rate-limiting-sla-release-notes">Rate-limiting SLA</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>401 - Request blocked due to invalid client credentials (client ID or client secret) provided</p></div></div></td></tr><tr><td><div><div><p>429 - Quota exceeded; requests blocked until the current window finishes</p></div></div></td></tr></tbody></table>

## Summary

The Rate-Limiting Service Level Agreement (SLA) policy enables you to control incoming traffic to an
API by limiting the number of requests that the API can receive within a given timespan. When the
limit is reached before the time expires, the policy rejects all requests, thereby avoiding any
additional load on the backend API.

To apply the Rate-Limiting SLA policy to an API, you must first create a contract between the API
and a registered client application. The number of requests that an API can receive within a given
time is defined in the [contracts](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task) section
in API Manager.

Each request must be identified by a client ID and an optional client secret (depending on the
policy configuration). To review how to obtain the client credentials of a registered client
application, see
[Obtaining Client Credentials of a Registered Application](https://docs.mulesoft.com/api-manager/latest/access-client-app-id-task).

> [!NOTE] A Rate-Limiting SLA policy applied to an Omni Gateway API is scoped to replicas, not the
> gateway.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Rate-Limiting SLA policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Client ID Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client Application’s ID for a Contract of the API</p></div></div></td><td><div><div><p>Only one rate-limiting algorithm is created per ID: <code>#[attributes.headers['client_id']]</code> This example looks for an HTTP header called ‘client_id’ and uses its value.</p></div></div></td></tr><tr><td><div><div><p>Client Secret Expression</p></div></div></td><td><div><div><p>A DataWeave expression that resolves the Client application’s client secret for a contract of the API</p></div></div></td><td><div><div><p>This is an optional value. Example: <code>#[attributes.headers['client_secret']]</code></p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the quota is shared among Omni Replicas</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Defines whether to expose the <a href="#response-header">x-ratelimit headers,</a> as part of the response</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr><tr><td><div><div><p>Block on unknown quota</p></div></div></td><td><div><div><p>For policies using distributed rate limiting, block requests if the policy can’t retrieve the quota from shared storage. If not enabled and the quota can’t be retrieved, no rate limiting is applied.</p></div></div></td><td><div><div><p>Checked or unchecked</p></div></div></td></tr></tbody></table>

> [!NOTE] If you enable the distributed rate limiting, the policy resizes time windows under 10
> seconds linearly. For example, if you configure a maximum of 10 requests per 5 seconds, the policy
> resizes that window to a maximum of 20 requests per 10 seconds.

## Enable Shared Storage

Distributed Rate-Limiting requires Shared Storage to be enabled. For more information about Shared
Storage, refer to
[Configuring Redis Shared Storage for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config).

## How This Policy Works

The Rate-Limiting SLA policy monitors the number of requests made in the current window (the
available quota), allowing the requests to reach the backend only if the available quota is greater
than zero.

Because each client defines a separate available quota for their window, the client application must
define an SLA with the API (a contract). Therefore, to verify whether the request is within the SLA
limit, you must define a way to obtain the client ID from the request, and optionally the client
Secret.

After a contract is created between a client application and an API, API gateway automatically
manages these contracts by monitoring your API Manager configurations. Additionally, API gateway
implements high-availability strategies in case of unexpected downtime in the Anypoint Platform
management plane.

To understand how the Rate-Limiting SLA policy works, consider an example in which the configuration
of an SLA of 3 requests every 10 seconds for the client with ID “ID#1” allows or restricts the
request, based on the quota available in that window:

![A timeline chart that displays both accepted and rejected client requests within a specified window](/mulesoft/current/en-us/gateway/latest/_images/rate-limiting-sla-general.png)

In the example:

- Requests of client with ID “ID#1”:

In the first window, because the quota is reached with the third request, all subsequent requests
are rejected until the window closes. In the second window, only two of the three requests are
processed. Because the time elapses in this window, the remaining quota is unused.

An accepted request passes through the API to the backend. Conversely, a rejected request displays a
`429 status for HTTP` (or 400, or 500 if the API is WSDL) and does not reach the backend.

- Requests of Client with ID “ID#2”:

Because the client has no contract defined for the API, every request is rejected , and therefore no
request is allowed.

An API might have several contracts, each with its own SLA. The Rate-Limiting SLA policy
independently monitors the quota (and windows) available for each client by creating one
rate-limiting algorithm per contract. With the first request to the API, algorithms are created
using the _lazy creation_ strategy.

## FAQ

**When does the window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

It uses a fixed window.

**What happens when the quota is exhausted?**

The algorithm is created on demand, when the first request is received. This event fixes the time
window. Each request consumes the request quota from the current window until the time expires.

When the request quota is exhausted, the Rate-Limiting SLA policy rejects the request. When the time
window closes, the request quota is reset and a new window of the same fixed size starts.

**What happens if I define multiple limits within an SLA ?**

The policy creates one algorithm for each Limit with the request quota per time window
configuration. Therefore, when multiple limits are configured, every algorithm must have its own
available quota within the current window for the request to be accepted.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of available quota

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until a new window starts

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

> [!NOTE] When on distributed mode, the X-Ratelimit-Remaining header is not perfectly synchronized
> with all the replicas. With multiple replicas on distributed mode, the X-Ratelimit-Remaining
> header is an estimation of how much quota the replica has available for itself. It does not
> represent the actual value of the remaining quota available for the API.
>
> The following describes a valid scenario:
>
> - Created a SLA tier name "Titanium" having rate limit of "999999999 req per 10 min"
>
> - Sent 1 request to replica 1 → x-ratelimit-remaining : 999999998
>
> - Sent 1 request to replica 2 → x-ratelimit-remaining : 899999998
>
> This does not mean that the quota will be surpassed.

**When should I use Rate Limiting instead of Rate-Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=7cfdb2bec71d00f558b2ce17b68653133da3c112472ddee834df01e8ff6fb90f url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-shared-storage.md -->

---
product: Omni Gateway
version: 1.13
---

# Redis Shared Storage Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring shared storage, MuleSoft recommends placing the Redis shared storage service as
close to Omni Gateway as possible.

If the Redis shared storage service is available locally in the same cluster or the same Virtual
Private Cloud (VPC), a mutual authentication Transport Layer Security (mTLS) connection is not
required to communicate with the shared storage.

To configure the connection between Omni Gateway and the Redis shared storage service, see:

- [Configure Redis Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config)

- [Configure Redis Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-shared-storage-config)

The following diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

You can place the Redis shared storage within the same Kubernetes cluster as Omni Gateway or
instantiated within the same VPC as Omni Gateway:

## Redis Shared Storage in the Same Cluster

![The Redis shared storage is in the same cluster as the Omni Gateway replicas](/mulesoft/current/en-us/gateway/1.13/_images/redis-same-cluster.png)

## Redis Shared Storage in the Same VPC

![The Redis shared storage is in the same VPC as the Omni Gateway replicas but is not in the same cluster](/mulesoft/current/en-us/gateway/1.13/_images/redis-same-vpc.png)

## See Also

- [Configure Redis Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config)

- [Configure Redis Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-shared-storage-config)

- [Configuring Omni Gateway Configuration Caching in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-replica-caching)

<!-- document id=6f1b49e737826299c723deea3fffa8c646f810eb764119ca8ff46d2496c33866 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-shared-storage.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Redis Shared Storage Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring shared storage, MuleSoft recommends placing the Redis shared storage service as
close to Omni Gateway as possible.

If the Redis shared storage service is available locally in the same cluster or the same Virtual
Private Cloud (VPC), a mutual authentication Transport Layer Security (mTLS) connection is not
required to communicate with the shared storage.

To configure the connection between Omni Gateway and the Redis shared storage service, see:

- [Configure Redis Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config)

- [Configure Redis Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/latest/local-shared-storage-config)

The following diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

You can place the Redis shared storage within the same Kubernetes cluster as Omni Gateway or
instantiated within the same VPC as Omni Gateway:

## Redis Shared Storage in the Same Cluster

![The Redis shared storage is in the same cluster as the Omni Gateway replicas](/mulesoft/current/en-us/gateway/latest/_images/redis-same-cluster.png)

## Redis Shared Storage in the Same VPC

![The Redis shared storage is in the same VPC as the Omni Gateway replicas but is not in the same cluster](/mulesoft/current/en-us/gateway/latest/_images/redis-same-vpc.png)

## See Also

- [Configure Redis Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-shared-storage-config)

- [Configure Redis Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/latest/local-shared-storage-config)

- [Configuring Omni Gateway Configuration Caching in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-replica-caching)

<!-- document id=704a91a6ac983af22dfb3b5d4c32c622d8cc9aaa4be8ecf4c5f93f3a4ccf7fc8 url=/mulesoft/current/en-us/gateway/1.12/policies-included-regex-prompt-guard.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, llm, prompt guard, regex, prompt injection
---

# Regex Prompt Guard Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Regex Prompt Guard</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks LLM requests that match deny-list regex patterns</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.11.4</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Request blocked because prompt content matched one or more denied patterns</p></td></tr></tbody></table>

## Summary

> [!NOTE] This policy supports OpenAI and Anthropic input formats.

The Regex Prompt Guard policy scans LLM prompts and blocks requests when prompt content matches
regex deny-list patterns.

The policy uses the Rust [regex crate](https://crates.io/crates/regex) which supports RE2-style
expressions to guarantee linear-time matching and eliminate the backtracking risk.

For example, you can use the policy to block attacks such as:

- Prompt injection

- Jailbreak attempts

- SQL injection patterns

- HTML script injection

## Configuring Policy Parameters

### Flex Gateway Local Mode

The Regex Prompt Guard policy isn’t supported in Local Mode.

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Pattern Name</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Human-readable pattern name. The policy includes this value in the blocked-response details.</p></div></div></td></tr><tr><td><div><div><p>Regex Pattern</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Regex expression used to match prompt content. Use <code>(?i)</code> for case-insensitive matching. See the Regex Support section for supported and unsupported regex features.</p></div></div></td></tr></tbody></table>

## Response on Block

When a request is blocked, the policy returns a response body containing the matched deny patterns:

```json
{
  "error": "Request blocked - content matches denied pattern",
  "matched_patterns": ["prompt-injection"]
}
```

## Regex Support

The Regex Prompt Guard Policy uses the Rust [regex crate](https://crates.io/crates/regex) which
supports RE2-style expressions to guarantee linear-time matching and eliminate the backtracking
risk. This ensures that customer-supplied regex patterns can’t negatively impact gateway performance
or availability.

The Regex Prompt Guard policy doesn’t support Perl Compatible Regular Expressions (PCRE), but
supports these PCRE features:

- Standard character classes

- Alternation

- Grouping

- Greedy or lazy quantifiers

- Anchors

- Inline flags, such as `(?i)`, for case-insensitivity.

These PCRE-specific features aren’t supported:

- Lookaround assertions: `(?=…​)`, `(?!…​)`, `(?⇐…​)`, `(?<!…​)`

- Backreferences: `\1`, `\2`, `(?P=name)`

- Recursive or subroutine calls: `(?R)`, `(?1)`

- Possessive quantifiers: ``a*`, `a+``

- Special constructs: `\G`, `\K`, and conditional patterns `(?(1)yes|no)`

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of Model Proxy and
  routing

- [LLM Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-llm-token-rate-limit) - Token-based rate
  limiting for Model Proxy

<!-- document id=d85dd18739007cfe1e49bea6bfd41ccaaeea5fac62ee2953b99e271321f6879c url=/mulesoft/current/en-us/gateway/1.13/policies-included-regex-prompt-guard.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, llm, prompt guard, regex, prompt injection
---

# Regex Prompt Guard Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Regex Prompt Guard</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks LLM requests that match deny-list regex patterns</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.4</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/regex-prompt-guard-policy-release-notes">Regex Prompt Guard Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Request blocked because prompt content matched one or more denied patterns</p></td></tr></tbody></table>

## Summary

> [!NOTE] This policy supports OpenAI and Anthropic input formats.

The Regex Prompt Guard policy scans LLM prompts and blocks requests when prompt content matches
regex deny-list patterns.

The policy uses the Rust [regex crate](https://crates.io/crates/regex) which supports RE2-style
expressions to guarantee linear-time matching and eliminate the backtracking risk.

For example, you can use the policy to block attacks such as:

- Prompt injection

- Jailbreak attempts

- SQL injection patterns

- HTML script injection

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Regex Prompt Guard policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Pattern Name</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Human-readable pattern name. The policy includes this value in the blocked-response details.</p></div></div></td></tr><tr><td><div><div><p>Regex Pattern</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>RE2-style regex expression used to match prompt content. Use <code>(?i)</code> for case-insensitive matching. See the Summary section for supported and unsupported regex features.</p></div></div></td></tr></tbody></table>

## Response on Block

When a request is blocked, the policy returns a response body containing the matched deny patterns:

```json
{
  "error": "Request blocked - content matches denied pattern",
  "matched_patterns": ["prompt-injection"]
}
```

## Regex Support

The Regex Prompt Guard Policy uses the Rust [regex crate](https://crates.io/crates/regex) which
supports RE2-style expressions to guarantee linear-time matching and eliminate the backtracking
risk. This ensures that customer-supplied regex patterns can’t negatively impact gateway performance
or availability.

The Regex Prompt Guard policy doesn’t support Perl Compatible Regular Expressions (PCRE), but
supports these PCRE features:

- Standard character classes

- Alternation

- Grouping

- Greedy or lazy quantifiers

- Anchors

- Inline flags, such as `(?i)`, for case-insensitivity.

These PCRE-specific features aren’t supported:

- Lookaround assertions: `(?=…​)`, `(?!…​)`, `(?⇐…​)`, `(?<!…​)`

- Backreferences: `\1`, `\2`, `(?P=name)`

- Recursive or subroutine calls: `(?R)`, `(?1)`

- Possessive quantifiers: ``a*`, `a+``

- Special constructs: `\G`, `\K`, and conditional patterns `(?(1)yes|no)`

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of model proxies and
  routing

- [LLM Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-llm-token-rate-limit) - Token-based rate
  limiting for model proxies

<!-- document id=d92245757fdca3b1ba1a180cac315baaa90737f53f1cf138fa31c0703116f6b3 url=/mulesoft/current/en-us/gateway/latest/policies-included-regex-prompt-guard.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, prompt guard, regex, prompt injection
---

# Regex Prompt Guard Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Regex Prompt Guard</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Blocks LLM requests that match deny-list regex patterns</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.4</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/regex-prompt-guard-policy-release-notes">Regex Prompt Guard Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Request blocked because prompt content matched one or more denied patterns</p></td></tr></tbody></table>

## Summary

> [!NOTE] This policy supports OpenAI and Anthropic input formats.

The Regex Prompt Guard policy scans LLM prompts and blocks requests when prompt content matches
regex deny-list patterns.

The policy uses the Rust [regex crate](https://crates.io/crates/regex) which supports RE2-style
expressions to guarantee linear-time matching and eliminate the backtracking risk.

For example, you can use the policy to block attacks such as:

- Prompt injection

- Jailbreak attempts

- SQL injection patterns

- HTML script injection

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Regex Prompt Guard policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Pattern Name</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Human-readable pattern name. The policy includes this value in the blocked-response details.</p></div></div></td></tr><tr><td><div><div><p>Regex Pattern</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>RE2-style regex expression used to match prompt content. Use <code>(?i)</code> for case-insensitive matching. See the Summary section for supported and unsupported regex features.</p></div></div></td></tr></tbody></table>

## Response on Block

When a request is blocked, the policy returns a response body containing the matched deny patterns:

```json
{
  "error": "Request blocked - content matches denied pattern",
  "matched_patterns": ["prompt-injection"]
}
```

## Regex Support

The Regex Prompt Guard Policy uses the Rust [regex crate](https://crates.io/crates/regex) which
supports RE2-style expressions to guarantee linear-time matching and eliminate the backtracking
risk. This ensures that customer-supplied regex patterns can’t negatively impact gateway performance
or availability.

The Regex Prompt Guard policy doesn’t support Perl Compatible Regular Expressions (PCRE), but
supports these PCRE features:

- Standard character classes

- Alternation

- Grouping

- Greedy or lazy quantifiers

- Anchors

- Inline flags, such as `(?i)`, for case-insensitivity.

These PCRE-specific features aren’t supported:

- Lookaround assertions: `(?=…​)`, `(?!…​)`, `(?⇐…​)`, `(?<!…​)`

- Backreferences: `\1`, `\2`, `(?P=name)`

- Recursive or subroutine calls: `(?R)`, `(?1)`

- Possessive quantifiers: ``a*`, `a+``

- Special constructs: `\G`, `\K`, and conditional patterns `(?(1)yes|no)`

## See Also

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy) - Overview of model proxies and
  routing

- [LLM Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/latest/policies-included-llm-token-rate-limit) - Token-based rate
  limiting for model proxies

<!-- document id=ae3a0b2a019413d7e2808d419f3b257cbe788a23e111611d318106db14af64b4 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-reg-run.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Flex Gateway to configure API instances, you must register and start the
gateway.

There are three ways to register Flex Gateway in Connected Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run-up): If you have a username and
  password for Anypoint Platform, you can use these credentials to register your Flex Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Flex
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run-token): If you do not have a username or
  password for Anypoint Platform, you can use a registration token generated by the Runtime Manager
  UI. The token is valid for four hours.

<!-- document id=e7689c5320fb5568db3a2518549f08e506777fceff888ed1bcbf7b5522efb725 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-reg-run.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Flex Gateway to configure API instances, you must register and start the
gateway.

There are three ways to register Flex Gateway in Connected Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run-up): If you have a username and
  password for Anypoint Platform, you can use these credentials to register your Flex Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Flex
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run-token): If you do not have a username or
  password for Anypoint Platform, you can use a registration token generated by the Runtime Manager
  UI. The token is valid for four hours.

<!-- document id=c9bb6c1771da0ec01dc18f689d416b7edccc428b6bf224d7be40ceeaf9980212 url=/mulesoft/current/en-us/gateway/1.12/flex-local-reg-run.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Flex Gateway to configure API instances, you must register and start the
gateway.

There are three options for registering Flex Gateway in Local Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run-up): If you have a username
  and password for Anypoint Platform, you can use these credentials to register your Flex Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Flex
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run-token): If you do not have a username or
  password for Anypoint Platform, you can use a registration token generated by the Runtime Manager
  UI. The token is valid for four hours.

<!-- document id=4789500e61988ae092312b059d6a02a53b13115803fa660f9fb25ee88215dd4b url=/mulesoft/current/en-us/gateway/1.9/flex-local-reg-run.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running Flex Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Flex Gateway to configure API instances, you must register and start the
gateway.

There are three options for registering Flex Gateway in Local Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run-up): If you have a username
  and password for Anypoint Platform, you can use these credentials to register your Flex Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Flex
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run-token): If you do not have a username or
  password for Anypoint Platform, you can use a registration token generated by the Runtime Manager
  UI. The token is valid for four hours.

<!-- document id=3862f4bc515c4e37b6cad80508ab44378a6cc186cf7130dc295acb235867f3b2 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-reg-run-app.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running in Connected Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Connected App in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

<!-- document id=848645b2f8989ccde5338ce98b2806e88efd27dbd15eee269bc1e9f59b48a670 url=/mulesoft/current/en-us/gateway/1.13/conn-reg-run-app.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running in Connected Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Connected App in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

<!-- document id=2052f75238fd4d1632279085af7d17312f1553206b9831c5f6db7a9e6dd96d2c url=/mulesoft/current/en-us/gateway/1.9/flex-conn-reg-run-app.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running in Connected Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian (Bullseye, Bookworm)

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- SUSE Linux Enterprise (SLES 15 SP3)

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

- Ubuntu (Focal, Jammy)

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Connected App in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

<!-- document id=0f9110dbd043de159b2cf6169cfbcd1724a9c7af89671b363ef924664e72b17a url=/mulesoft/current/en-us/gateway/latest/conn-reg-run-app.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running in Connected Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Connected App in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Connected App in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

<!-- document id=ce5cbda6795a6a91b902eb0c481899db17ae80e363bddebed702bc0aab97b7d3 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-reg-run-token.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running in Connected Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Flex
    Gateway

    Navigate to Runtime Manager, select **Flex Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Token in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

<!-- document id=165973c2fc2276ef979305bfd2fa51038d7e8d42377a5ebccb809ed2972cff02 url=/mulesoft/current/en-us/gateway/1.13/conn-reg-run-token.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running in Connected Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Omni
    Gateway

    Navigate to Runtime Manager, select **Omni Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Token in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

<!-- document id=50d057a55696a3e6f5be966d814dcfd670d772a96b0bf8c9baf20619fe1c7419 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-reg-run-token.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running in Connected Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Flex
    Gateway

    Navigate to Runtime Manager, select **Flex Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian (Bullseye, Bookworm)

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- SUSE Linux Enterprise (SLES 15 SP3)

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

- Ubuntu (Focal, Jammy)

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Token in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

<!-- document id=90080f87e14248f29c115b29bdcad7e4a4cb90d66f8e6f01306e2a45f5ab3202 url=/mulesoft/current/en-us/gateway/latest/conn-reg-run-token.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running in Connected Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Omni
    Gateway

    Navigate to Runtime Manager, select **Omni Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Token in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Token in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

<!-- document id=20b324b96469689395ea9be2e986f60cca9b8aabcd84e4e1884997f889eb8dce url=/mulesoft/current/en-us/gateway/1.12/flex-conn-reg-run-up.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running in Connected Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Username and Password in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

<!-- document id=9b4014fdc1b4302aafbbb9bf2dc9b0b8893e6702d2814c6a7770885472d58db7 url=/mulesoft/current/en-us/gateway/1.13/conn-reg-run-up.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running in Connected Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Username and Password in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

<!-- document id=82cf03d5ae993c8421890a899f75fe2a1f447531b1a7e1f81906f4af63c13074 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-reg-run-up.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running in Connected Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian (Bullseye, Bookworm)

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- SUSE Linux Enterprise (SLES 15 SP3)

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

- Ubuntu (Focal, Jammy)

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Username and Password in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Flex Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

<!-- document id=bba2202ffe70fced4d51d6475093386e4581d4e34fb82faf35de854df2f00033 url=/mulesoft/current/en-us/gateway/latest/conn-reg-run-up.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running in Connected Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Register and Run with a Username and Password in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster and
connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is
present and connected to Anypoint Platform.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Connected Mode, Omni Gateway typically serves as an ingress or Edge API gateway that receives
traffic from outside of the cluster. Omni Gateway can also act as a standalone gateway for internal
(east-west) services.

Most management takes place within Anypoint Platform:

- Deploy APIs to your cluster.

- Apply policies and other configurations.

- Create resources (_with the exception_ of Configuration and Service resources).

In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the
following resource types: Configuration, Service, Extension, and PolicyBinding of types `tls`,
`tls-inbound`, and `tls-outbound`. For more info about resources, see
[Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--connected=true \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your gateway in the UI.
Notice that your gateway’s status is **Not Running**. Refresh the page, if necessary.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Connected Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set gateway.mode=connected \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local
    Mode.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

In Runtime Manager, click **← Omni Gateway** in the left navigation to find your new gateway in the
UI. Notice that your gateway’s current status is **Running**. Refresh the page, if necessary.

> [!NOTE] After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI.
> Otherwise, the UI continues to list the gateway even if it is no longer running or connected.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

<!-- document id=1de404e3f64dddddad68528eecd3f1ca92a656a6b769245b9c28b5f30dbdc660 url=/mulesoft/current/en-us/gateway/1.12/flex-local-reg-run-app.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running in Local Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Connected App in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Connected App in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Connected App in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

<!-- document id=8d305885ab8d474cb0d07d32a66377fd125d2f1f38f4c8f9fcbb0ca3074e7748 url=/mulesoft/current/en-us/gateway/1.13/local-reg-run-app.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running in Local Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Connected App in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Connected App in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Connected App in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

<!-- document id=2f7f9808d58a079be44d7749dfb783846e43756185e584fbc78cd2053525dbde url=/mulesoft/current/en-us/gateway/1.9/flex-local-reg-run-app.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running in Local Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian (Bullseye, Bookworm)

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- SUSE Linux Enterprise (SLES 15 SP3)

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

- Ubuntu (Focal, Jammy)

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Connected App in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Connected App in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Connected App in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

<!-- document id=151ba2b11b9d484903e9425bae7b0f99c99f7c9e527aa566d44fc6af7372dfbd url=/mulesoft/current/en-us/gateway/latest/local-reg-run-app.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running in Local Mode with a Connected App

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Configure a Connected App](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)

  - Include the following scopes:

    - Read Servers

    - Manage Servers

    - View Organization

  - Save the **Id** and **Secret** of the Connected app you configure.

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

## Register and Run with a Connected App as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Connected App in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Connected App in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Connected App in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Connected App in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Connected App in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--client-id` = the Id for the Connected App you configured in Access Management

- `--client-secret` = the Secret for the Connected App you configured in Access Management

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--client-id=<your-connected-app-client-id> \
--client-secret=<your-connected-app-client-secret> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

<!-- document id=abe6d9194732117ea32e2b8f7e6b66dae95c6b2a7d6e02ba31731cf810467daa url=/mulesoft/current/en-us/gateway/1.12/flex-local-reg-run-token.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running in Local Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Flex
    Gateway

    Navigate to Runtime Manager, select **Flex Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Token in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Token in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Token in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

<!-- document id=ded3a3e7e713ec75f6e0f6e5546ad219923eed9449fef1eb6db75199ff542645 url=/mulesoft/current/en-us/gateway/1.13/local-reg-run-token.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running in Local Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Omni
    Gateway

    Navigate to Runtime Manager, select **Omni Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Token in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Token in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Token in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

<!-- document id=27518334f58164099277e4062d25c9108fa3ac1d26b982abe36b34f630a28951 url=/mulesoft/current/en-us/gateway/1.9/flex-local-reg-run-token.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running in Local Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Flex
    Gateway

    Navigate to Runtime Manager, select **Flex Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian (Bullseye, Bookworm)

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- SUSE Linux Enterprise (SLES 15 SP3)

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

- Ubuntu (Focal, Jammy)

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Token in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Token in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Token in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

<!-- document id=06a4dbc8fdbf0dfe35f3016ae35d6b81f9b974cd75e0bbc1eb01e0e578b8d9f0 url=/mulesoft/current/en-us/gateway/latest/local-reg-run-token.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running in Local Mode with a Token

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The registration **token** for the environment in Anypoint Platform where you want to run Omni
    Gateway

    Navigate to Runtime Manager, select **Omni Gateways** in the left navigation, and click **Add
    Gateway** to generate set of instructions that includes a command block with the registration
    token.

## Register and Run with a Token as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Token in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Token in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Token in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Token in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Token in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--token` = the registration token for your environment in Anypoint Platform

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--token=<your-registration-token> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

<!-- document id=2894b9b4241d0435523f076575c5393dc83d153508d680ad0b300e5d24f1cfb3 url=/mulesoft/current/en-us/gateway/1.12/flex-local-reg-run-up.md -->

---
product: Omni Gateway
version: 1.12
---

# Registering and Running in Local Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Username and Password in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Username and Password in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

<!-- document id=df3ec8edb3a7b27fd13f83c423e48e8e6b59fb267793b11faac0c9b94b2cbfc0 url=/mulesoft/current/en-us/gateway/1.13/local-reg-run-up.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running in Local Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Username and Password in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Username and Password in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.13/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

<!-- document id=0fa69c69ef74278f4c824cc5125ea487430ad731617b211ca907f85c4c24b44f url=/mulesoft/current/en-us/gateway/1.9/flex-local-reg-run-up.md -->

---
product: Omni Gateway
version: 1.9
---

# Registering and Running in Local Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Flex Gateway, you must complete the following tasks:

- [Install a Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Flex Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Flex Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian (Bullseye, Bookworm)

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- SUSE Linux Enterprise (SLES 15 SP3)

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

- Ubuntu (Focal, Jammy)

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Start Commands

Start Flex Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Flex Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Username and Password in a Container

You can register and run Flex Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Username and Password in a Podman Container

To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Flex Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Flex Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster.

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Flex Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to
your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to
your gateway.

Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex
Gateway manages `Ingress` resources, see
[Configure Flex Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Flex Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Flex Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Flex Gateway

Register your Flex Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Flex Gateway. If you
> lose them you can no longer connect your Flex Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Flex Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Flex Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-management).

Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

<!-- document id=4eef0b69cafc9be0c6467e58b5492d84ce9e6faa6ef19a951315c4fe8b44b4f1 url=/mulesoft/current/en-us/gateway/latest/local-reg-run-up.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running in Local Mode with a Username and Password

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-container-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#openshift"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-openshift-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Linux</a></p></div></div></td><td><div><div><p><a href="#container">Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Kubernetes</a></p></div></div></td><td><div><div><p><a href="#openshift">OpenShift</a></p></div></div></td></tr></tbody></table>

## Before You Begin

Before registering Omni Gateway, you must complete the following tasks:

- [Install an Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint
  Platform admin

- Collect the following information from your Anypoint Platform instance:

  - The **Organization ID** for the organization where you want to run Omni Gateway

    See
    [Find your Organization ID](https://docs.mulesoft.com/access-management/managing-business-groups#find-your-organization-id)
    for more information on how to find your Organization ID.

  - The **Environment ID** for the environment where you want to run Omni Gateway

    See
    [What API Manager Looks Like](https://docs.mulesoft.com/api-manager/latest/latest-overview-concept#what-api-manager-looks-like)
    for more information on how to find your Environment ID.

  - The **Username** and **Password** of a user with _Read Servers_ and _Manage Servers_ permissions
    for Runtime Manager

## Register and Run with a Username and Password as a Linux Service

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

```ssh
flexctl registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Start Commands

Start Omni Gateway with the following command:

```ssh
sudo systemctl start flex-gateway
```

Verify that the Omni Gateway service is running successfully:

```ssh
systemctl list-units flex-gateway*
```

If `flex-gateway.service` has a status of `active`, Omni Gateway is successfully running.

```text
  UNIT                              LOAD   ACTIVE SUB     DESCRIPTION
  flex-gateway.service              loaded active running Application
```

## Register and Run with a Username and Password in a Container

You can register and run Omni Gateway for use in one of the following containers:

<table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="15%" width="15%"></a></span></p></div></div></td><td><div><div><p><span><a href="#podman"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-podman-logo.png" alt="12%" width="12%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#docker">Docker</a></p></div></div></td><td><div><div><p><a href="#podman">Podman</a></p></div></div></td></tr></tbody></table>

### Register and Run with a Username and Password in a Docker Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

### Register and Run with a Username and Password in a Podman Container

To register an Omni Gateway with Anypoint Platform, you must enter the registration command and then
the start command. Each command includes information specific to your Anypoint Platform instance and
**must be updated before** executing. See [Before You Begin](#prereqs) for more information on how
to find the information you will need.

#### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

#### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

> [!IMPORTANT] Create a new directory called `flex-registration` (or similar) and then run the
> registration command in this new directory. The command creates registration files in this
> location.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

#### Start Command

Run the following start command in the same directory where you ran the registration command:

```ssh
podman run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
docker.io/mulesoft/flex-gateway
```

> [!NOTE] Specify an optional name you want to assign to your Omni Replica by including the
> following: `-e FLEX_NAME=<name-for-flex-replica> \`.

The output logs should include this line:

```ssh
[flex-gateway-envoy][info] all dependencies initialized. starting workers
```

## Register and Run with a Username and Password in a Kubernetes Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway.

Complete the following steps:

1.  [Collect Your Registration Data](#options-k8s)

2.  [Register Omni Gateway](#reg-k8s)

3.  [Install Helm Chart into the Namespace](#deploy-k8s)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-k8s) for configuration options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## Register and Run with a Username and Password in an OpenShift Cluster

Register Omni Gateway, and then use Helm to deploy Omni Gateway to a node in your cluster.

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

From the command line, OpenShift procedures match Kubernetes procedures. Complete the following
steps:

1.  [Collect Your Registration Data](#options-openshift)

2.  [Register Omni Gateway](#reg-openshift)

3.  [Install Helm Chart into the Namespace](#deploy-openshift)

In Local Mode, Omni Gateway typically acts as an ingress controller that manages external access to
your cluster. Omni Gateway can also act as a standalone gateway for internal (east-west) traffic.

When using this mode, you must know what resources to create and apply, and use `kubectl apply` to
deploy Kubernetes targets and resources such as APIs, policies, or Omni Gateway-related resources to
your gateway.

Omni Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway
routing rules. You provide this configuration through a YAML file. The file supports other
properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy
server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Omni
Gateway manages `Ingress` resources, see
[Configure Omni Gateway as an Ingress Controller in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-k8-ingress-class).

### Collect Your Registration Data

Before registering your Omni Gateway instance, collect information for the following registration
command options:

- `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_
  permissions for Runtime Manager

- `--environment` = the Environment Id for the environment in Anypoint Platform where you want the
  Omni Gateway to run

- `--organization` = your Organization ID in Anypoint Platform

- `--split` (optional) = the flag that determines whether registration information should split into
  multiple files. The default value is `false`.

  If `split` is set to `true`, registration information is split into two files: `registration.yaml`
  and `certificate.yaml`. If `false`, all registration information is contained in one file:
  `registration.yaml`.

- `--output-directory` (optional) = the directory in which registration information is output

- `my-gateway` = the name you want to assign the gateway cluster

### Register Omni Gateway

Register your Omni Gateway instance using the data that you gathered for the command options.

You can register using one of the following container runtimes:

**Docker**

Run the following command to register using Docker:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

**Podman**

Run the following command to register using Podman:

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \
registration create \
--username=<your-username> \
--password=<your-password> \
--environment=<your-environment-id> \
--organization=<your-org-id> \
--output-directory=/registration \
my-gateway
```

Use `sudo` if you encounter file permission issues when running this command.

> [!NOTE] If you are in Europe you will need to add the
> `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag to your command.

In the output directory, you should see the following new registration file(s):

- `registration.yaml`

- `certificate.yaml` (generated only if the `split` registration parameter is set to `true`,
  otherwise certificate information will be contained in `registration.yaml`)

> [!IMPORTANT] These generated files are credentials for you to connect your Omni Gateway. If you
> lose them you can no longer connect your Omni Gateway.

### Install Helm Chart into the Namespace

A Helm chart installs Omni Gateway, monitoring tools, and applications. A minimum Helm version of
3.0.0 is required. Refer to [Helm Chart Settings](#helm-options-openshift) for configuration
options.

1.  Add a Helm repository named `flex-gateway` for your chart:

    ```helm
    helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
    ```

    The command either adds the repository or skips this process if a Helm repository with that name
    already exists on your machine:

    - If the repository is new, the command returns the following message:

      "flex-gateway" has been added to your repositories

    - If the repository already exists, the command returns the following message:

      "flex-gateway" already exists with the same configuration, skipping

2.  Run `helm repo up`.

    The command returns the following message:

    Hang tight while we grab the latest from your chart repositories... ...Successfully got an
    update from the "flex-gateway" chart repository Update Complete. ⎈Happy Helming!⎈

    If you have more than one Helm repository on your machine, the message in your terminal window
    lists all of the repositories.

3.  Run the Helm command for deploying your gateway in Local Mode:

    ```helm
    helm -n gateway upgrade -i --create-namespace \
    ingress flex-gateway/flex-gateway \
    --set-file registration.content=registration.yaml
    ```

    This command creates the `gateway` namespace and a release named `ingress` if they do not exist.
    You can use names of your choice for your namespace and release. The command syntax for the Helm
    repository and chart names is `<helm-repo-name>/<helm-chart-name>`.

    When you install Omni Gateway, a Service type `LoadBalancer` is created by default. You must
    have the appropriate permissions to create a load balancer in your cloud. If the load balancer
    is not provisioned or has issues with the provisioning process, you must choose another type by
    changing the `service.type` property during the installation.

    > [!NOTE] By default, Omni Gateways running in Kubernetes or Openshift use a readiness probe. If
    > there’s no API deployed to your Omni Gateway instance, the readiness state is `false`. This
    > isn’t an issue with custom readiness probe configurations.

    When successful, the command prints a message indicating an upgrade to your `ingress` release:

    Release "ingress" does not exist. Installing it now. NAME: ingress LAST DEPLOYED: Mon Mar 20
    21:36:19 2023 NAMESPACE: gateway STATUS: deployed REVISION: 1 TEST SUITE: None

    The `REVISION` value increments the `ingress` release by `1` each time you run this command with
    the same namespace, repository, and chart names. For example, if you run the command a second
    time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date
    of that revision.

### Helm Chart Settings

To modify the default Helm settings with new values, such as `resource` values for CPU and memory
settings, see
[Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart](https://docs.mulesoft.com/gateway/latest/gateway-k8-change-helm-settings).
For additional Helm chart configurations, see
[Managing Kubernetes Deployments](https://docs.mulesoft.com/gateway/latest/gateway-k8-management).

Before modifying a Helm chart for an Omni Gateway deployment, review the default Helm chart
settings:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window.

  Example:

  ```kubernetes
  helm show values flex-gateway/flex-gateway
  ```

  The example returns _default_ values of a repository and chart with the same name.

To view the Helm chart `README`, run `helm show readme <repository-name>/<chart-name>` from a
terminal window.

Example:

```kubernetes
helm show readme flex-gateway/flex-gateway
```

## See Also

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

<!-- document id=bdb2681286c0a3e0612709e181c004b71a0297098b23f528ba3cf3d74c8ce234 url=/mulesoft/current/en-us/gateway/1.13/conn-reg-run.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Omni Gateway to configure API instances, you must register and start the
gateway.

There are three ways to register Omni Gateway in Connected Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/1.13/conn-reg-run-up): If you have a username and
  password for Anypoint Platform, you can use these credentials to register your Omni Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/1.13/conn-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Omni
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/1.13/conn-reg-run-token): If you do not have a username or password
  for Anypoint Platform, you can use a registration token generated by the Runtime Manager UI. The
  token is valid for four hours.

<!-- document id=4437b96c656a3f34dc0b903d0156f55e4f22728bf3b8fe8e7e637fccd74b1af6 url=/mulesoft/current/en-us/gateway/latest/conn-reg-run.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Omni Gateway to configure API instances, you must register and start the
gateway.

There are three ways to register Omni Gateway in Connected Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/latest/conn-reg-run-up): If you have a username and
  password for Anypoint Platform, you can use these credentials to register your Omni Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/latest/conn-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Omni
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/latest/conn-reg-run-token): If you do not have a username or password
  for Anypoint Platform, you can use a registration token generated by the Runtime Manager UI. The
  token is valid for four hours.

<!-- document id=ab7eb59ad0edf442edf27b56891ced5165ac03080f8037b1f1d49404c1be6b94 url=/mulesoft/current/en-us/gateway/1.13/local-reg-run.md -->

---
product: Omni Gateway
version: 1.13
---

# Registering and Running Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Omni Gateway to configure API instances, you must register and start the
gateway.

There are three options for registering Omni Gateway in Local Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/1.13/local-reg-run-up): If you have a username and
  password for Anypoint Platform, you can use these credentials to register your Omni Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/1.13/local-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Omni
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/1.13/local-reg-run-token): If you do not have a username or password
  for Anypoint Platform, you can use a registration token generated by the Runtime Manager UI. The
  token is valid for four hours.

<!-- document id=f22fd5407f49da7770e235c5514a982ffa6251beb22fe4a154408f953c0dc3cf url=/mulesoft/current/en-us/gateway/latest/local-reg-run.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Registering and Running Omni Gateway in Local Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you can use your Omni Gateway to configure API instances, you must register and start the
gateway.

There are three options for registering Omni Gateway in Local Mode:

- [Register and Run using a Username and Password](https://docs.mulesoft.com/gateway/latest/local-reg-run-up): If you have a username and
  password for Anypoint Platform, you can use these credentials to register your Omni Gateway.

- [Register and Run using a Connected App](https://docs.mulesoft.com/gateway/latest/local-reg-run-app): If you do not have a username or
  password for Anypoint Platform, you can use connected app credentials to register your Omni
  Gateway.

- [Register and Run using a Token](https://docs.mulesoft.com/gateway/latest/local-reg-run-token): If you do not have a username or password
  for Anypoint Platform, you can use a registration token generated by the Runtime Manager UI. The
  token is valid for four hours.

<!-- document id=d46b72a07bb0af7a1e78b7be063520a996befd3224f7ff0f0dc53f567de79a81 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-renew-certificate.md -->

---
product: Omni Gateway
version: 1.12
---

# Renew Self-Managed Flex Gateway Registration

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This
certificate is generated when you register Flex Gateway in either Connected Mode or Local Mode.
Updating the certificate ensures the continued operation of your applications.

You update a certificate by renewing registration via the `flexctl registration renew` command.

- The `renew` command renews an existing Flex Gateway registration with Runtime Manager.

- For authentication, you run the `renew` command with either user credentials or with connected app
  credentials. Authentication with user credentials requires the `--username` and `--password`
  flags. Authentication with connected app credentials requires the `--client-id` and
  `--client-secret` flags.

You verify the renewal process via the `flexctl registration inspect` command.

- The `inspect` command extracts registration information you can use to verify whether the `renew`
  command was successful.

- You can also use the `inspect` command to first determine if renewing registration is actually
  required. The `inspect` command returns the certificate expiration date.

- You can verify (inspect) renewal by using the default method, or you can specify your existing
  registration file. If you run the `inspect` command without flags, the command inspects
  registration status by using the default method.

To avoid disruptions:

1.  [Download the latest version of Flex Gateway.](#before-you-begin)

2.  Renew your Flex Gateway registration.

    Choose one of two methods:

    - [Anypoint Platform User Credentials](#renew-with-user-password)

    - [Connected App Credentials](#renew-with-conn-app)

3.  Verify the success of the renewal process.

    Choose one of two methods:

    - [Default Method](#inspect-with-custom-url)

    - [Registration File](#inspect-with-reg-file)

## Before You Begin

To invoke the registration renewal `flexctl` command, download the latest version of Flex Gateway.
You don’t need to register and run this version of the gateway.

- [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

## Renew Registration with Anypoint Platform User Credentials

1.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

2.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --username=<your-username> --password=<your-password> \
     <path-to-registration-file>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your Anypoint Platform
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    > [!NOTE] Disable MFA for your Anypoint Platform account prior to running the `renew` command
    > with user credentials.

3.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

4.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

5.  Restart the Flex Gateway replica if one is already running.

## Renew Registration with Connected App Credentials

1.  If you don’t have a username or password for Anypoint Platform, you can
    [configure a connected app](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)
    via Anypoint Access Management.

    1.  Include the following scopes:

        - Read Servers

        - Manage Servers

        - View Organization

    2.  Save the **Id** and **Secret** of the connected app you configure, then use these
        credentials in the `renew` command.

2.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

3.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --client-id=<your-client-id> --client-secret=<your-client-secret> \
     <path-to-registration-file>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your connected app
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

4.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

5.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

6.  Restart the Flex Gateway replica if one is already running.

## Verify Registration Status with the Default Method

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect
```

Use `sudo` if you encounter file permission issues when running this command.

For Flex Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
docker exec -u $UID <container-name-or-id> flexctl registration inspect
```

For Flex Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
podman exec -u $UID <container-name-or-id> flexctl registration inspect
```

The output should include the date of certificate expiration. For example:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

## Verify Registration Status with a Registration File

You can inspect a registration by extracting the information from your `registration.yaml` file.
Specify the path and filename.

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect --file=<path-to-registration-file>
```

Use `sudo` if you encounter file permission issues when running this command.

For Flex Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
docker run --entrypoint flexctl \
-v <path-to-registration-directory>:/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

For Flex Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v <path-to-registration-directory>:/registration:Z \
-u $UID docker.io/mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

The output should include the date of certificate expiration:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

As an example, if your current directory contains the registration file, run the following command:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=/registration/registration.yaml
```

## Renew Registration for Flex Gateway Running in Kubernetes

The following example describes a scenario where Flex Gateway is installed in a `gateway` namespace
with an `ingress` release name, and where registration is stored in the Kubernetes database.

1.  Recover the `registration.yaml` file with the following `kubectl` command:

    ```ssh
    kubectl -n gateway get secret "$(kubectl -n gateway get deployment ingress -o=jsonpath='{.spec.template.spec.volumes[?(@.name=="registration")].secret.secretName}')" -o=jsonpath='{.data.registration\.yaml}' | base64 --decode > registration.yaml
    ```

    The command stores the registration file in `./registration.yaml`.

2.  Run the `flexctl registration renew` command, as described for Docker in previous sections:

    - [Renew with Anypoint Platform User Credentials](#renew-with-user-password)

    - [Renew with Connected App Credentials](#renew-with-conn-app)

3.  Upgrade Flex Gateway with the following `helm` command:

    ```ssh
    helm get values -n gateway ingress > values.yaml \
    && helm upgrade -n gateway ingress flex-gateway/flex-gateway --wait -f values.yaml --set-file registration.content=new/registration.yaml
    ```

## Get Help with the Renewal and Verification Commands

You can run the following `help` commands for information about usage:

- Renewal

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration renew --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration renew --help
  ```

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration renew --help
  ```

- Verification

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration inspect --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration inspect --help
  ```

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration inspect --help
  ```

## Renew an Expired Registration

Attempting to run Flex Gateway with an expired certificate in Connected Mode results in the
following:

- New replicas fail to download API configurations from Anypoint Platform, thereby becoming
  unusable. Existing clusters fail to reload.

- Logs and metrics fail to upload to Anypoint Platform. Troubleshooting using Anypoint Platform is
  not possible.

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

Attempting to run Flex Gateway with an expired certificate in Local Mode results in the following:

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

If a certificate expires, you can still invoke `flexctl registration renew`, which updates the
expired certificate.

## See Also

- [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

<!-- document id=489200c545dfbc5800d2e9e5bfaea4534265fea311d7fe2db22c5999f83b2b4a url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-renew-certificate.md -->

---
product: Omni Gateway
version: 1.9
---

# Renew Self-Managed Flex Gateway Registration

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This
certificate is generated when you register Flex Gateway in either Connected Mode or Local Mode.
Updating the certificate ensures the continued operation of your applications.

You update a certificate by renewing registration via the `flexctl registration renew` command.

- The `renew` command renews an existing Flex Gateway registration with Runtime Manager.

- For authentication, you run the `renew` command with either user credentials or with connected app
  credentials. Authentication with user credentials requires the `--username` and `--password`
  flags. Authentication with connected app credentials requires the `--client-id` and
  `--client-secret` flags.

You verify the renewal process via the `flexctl registration inspect` command.

- The `inspect` command extracts registration information you can use to verify whether the `renew`
  command was successful.

- You can also use the `inspect` command to first determine if renewing registration is actually
  required. The `inspect` command returns the certificate expiration date.

- You can verify (inspect) renewal by using the default method, or you can specify your existing
  registration file. If you run the `inspect` command without flags, the command inspects
  registration status by using the default method.

To avoid disruptions:

1.  [Download the latest version of Flex Gateway.](#before-you-begin)

2.  Renew your Flex Gateway registration.

    Choose one of two methods:

    - [Anypoint Platform User Credentials](#renew-with-user-password)

    - [Connected App Credentials](#renew-with-conn-app)

3.  Verify the success of the renewal process.

    Choose one of two methods:

    - [Default Method](#inspect-with-custom-url)

    - [Registration File](#inspect-with-reg-file)

## Before You Begin

To invoke the registration renewal `flexctl` command, download the latest version of Flex Gateway.
You don’t need to register and run this version of the gateway.

- [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

## Renew Registration with Anypoint Platform User Credentials

1.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

2.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --username=<your-username> --password=<your-password> \
     <path-to-registration-file>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your Anypoint Platform
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    > [!NOTE] Disable MFA for your Anypoint Platform account prior to running the `renew` command
    > with user credentials.

3.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

4.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

5.  Restart the Flex Gateway replica if one is already running.

## Renew Registration with Connected App Credentials

1.  If you don’t have a username or password for Anypoint Platform, you can
    [configure a connected app](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)
    via Anypoint Access Management.

    1.  Include the following scopes:

        - Read Servers

        - Manage Servers

        - View Organization

    2.  Save the **Id** and **Secret** of the connected app you configure, then use these
        credentials in the `renew` command.

2.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

3.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --client-id=<your-client-id> --client-secret=<your-client-secret> \
     <path-to-registration-file>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your connected app
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

4.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

5.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

6.  Restart the Flex Gateway replica if one is already running.

## Verify Registration Status with the Default Method

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect
```

Use `sudo` if you encounter file permission issues when running this command.

For Flex Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
docker exec -u $UID <container-name-or-id> flexctl registration inspect
```

For Flex Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
podman exec -u $UID <container-name-or-id> flexctl registration inspect
```

The output should include the date of certificate expiration. For example:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

## Verify Registration Status with a Registration File

You can inspect a registration by extracting the information from your `registration.yaml` file.
Specify the path and filename.

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect --file=<path-to-registration-file>
```

Use `sudo` if you encounter file permission issues when running this command.

For Flex Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
docker run --entrypoint flexctl \
-v <path-to-registration-directory>:/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

For Flex Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v <path-to-registration-directory>:/registration:Z \
-u $UID docker.io/mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

The output should include the date of certificate expiration:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

As an example, if your current directory contains the registration file, run the following command:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=/registration/registration.yaml
```

## Renew Registration for Flex Gateway Running in Kubernetes

The following example describes a scenario where Flex Gateway is installed in a `gateway` namespace
with an `ingress` release name, and where registration is stored in the Kubernetes database.

1.  Recover the `registration.yaml` file with the following `kubectl` command:

    ```ssh
    kubectl -n gateway get secret "$(kubectl -n gateway get deployment ingress -o=jsonpath='{.spec.template.spec.volumes[?(@.name=="registration")].secret.secretName}')" -o=jsonpath='{.data.registration\.yaml}' | base64 --decode > registration.yaml
    ```

    The command stores the registration file in `./registration.yaml`.

2.  Run the `flexctl registration renew` command, as described for Docker in previous sections:

    - [Renew with Anypoint Platform User Credentials](#renew-with-user-password)

    - [Renew with Connected App Credentials](#renew-with-conn-app)

3.  Upgrade Flex Gateway with the following `helm` command:

    ```ssh
    helm get values -n gateway ingress > values.yaml \
    && helm upgrade -n gateway ingress flex-gateway/flex-gateway --wait -f values.yaml --set-file registration.content=new/registration.yaml
    ```

## Get Help with the Renewal and Verification Commands

You can run the following `help` commands for information about usage:

- Renewal

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration renew --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration renew --help
  ```

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration renew --help
  ```

- Verification

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration inspect --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration inspect --help
  ```

  For Flex Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration inspect --help
  ```

## Renew an Expired Registration

Attempting to run Flex Gateway with an expired certificate in Connected Mode results in the
following:

- New replicas fail to download API configurations from Anypoint Platform, thereby becoming
  unusable. Existing clusters fail to reload.

- Logs and metrics fail to upload to Anypoint Platform. Troubleshooting using Anypoint Platform is
  not possible.

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

Attempting to run Flex Gateway with an expired certificate in Local Mode results in the following:

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

If a certificate expires, you can still invoke `flexctl registration renew`, which updates the
expired certificate.

## See Also

- [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

<!-- document id=5daf1506705e73fdce037810bb1702a16c73f0db521c50d652e9e94103b36fac url=/mulesoft/current/en-us/gateway/1.13/gateway-renew-certificate.md -->

---
product: Omni Gateway
version: 1.13
---

# Renew Self-Managed Omni Gateway Registration

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This certificate
is generated when you register Omni Gateway in either Connected Mode or Local Mode. Updating the
certificate ensures the continued operation of your applications.

You update a certificate by renewing registration via the `flexctl registration renew` command.

- The `renew` command renews an existing Omni Gateway registration with Runtime Manager.

- For authentication, you run the `renew` command with either user credentials or with connected app
  credentials. Authentication with user credentials requires the `--username` and `--password`
  flags. Authentication with connected app credentials requires the `--client-id` and
  `--client-secret` flags.

You verify the renewal process via the `flexctl registration inspect` command.

- The `inspect` command extracts registration information you can use to verify whether the `renew`
  command was successful.

- You can also use the `inspect` command to first determine if renewing registration is actually
  required. The `inspect` command returns the certificate expiration date.

- You can verify (inspect) renewal by using the default method, or you can specify your existing
  registration file. If you run the `inspect` command without flags, the command inspects
  registration status by using the default method.

To avoid disruptions:

1.  [Download the latest version of Omni Gateway.](#before-you-begin)

2.  Renew your Omni Gateway registration.

    Choose one of two methods:

    - [Anypoint Platform User Credentials](#renew-with-user-password)

    - [Connected App Credentials](#renew-with-conn-app)

3.  Verify the success of the renewal process.

    Choose one of two methods:

    - [Default Method](#inspect-with-custom-url)

    - [Registration File](#inspect-with-reg-file)

## Before You Begin

To invoke the registration renewal `flexctl` command, download the latest version of Omni Gateway.
You don’t need to register and run this version of the gateway.

- [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

## Renew Registration with Anypoint Platform User Credentials

1.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

2.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --username=<your-username> --password=<your-password> \
     <path-to-registration-file>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your Anypoint Platform
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    > [!NOTE] Disable MFA for your Anypoint Platform account prior to running the `renew` command
    > with user credentials.

3.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

4.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

5.  Restart the Omni Gateway replica if one is already running.

## Renew Registration with Connected App Credentials

1.  If you don’t have a username or password for Anypoint Platform, you can
    [configure a connected app](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)
    via Anypoint Access Management.

    1.  Include the following scopes:

        - Read Servers

        - Manage Servers

        - View Organization

    2.  Save the **Id** and **Secret** of the connected app you configure, then use these
        credentials in the `renew` command.

2.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

3.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --client-id=<your-client-id> --client-secret=<your-client-secret> \
     <path-to-registration-file>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your connected app
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

4.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

5.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

6.  Restart the Omni Gateway replica if one is already running.

## Verify Registration Status with the Default Method

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect
```

Use `sudo` if you encounter file permission issues when running this command.

For Omni Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
docker exec -u $UID <container-name-or-id> flexctl registration inspect
```

For Omni Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
podman exec -u $UID <container-name-or-id> flexctl registration inspect
```

The output should include the date of certificate expiration. For example:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

## Verify Registration Status with a Registration File

You can inspect a registration by extracting the information from your `registration.yaml` file.
Specify the path and filename.

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect --file=<path-to-registration-file>
```

Use `sudo` if you encounter file permission issues when running this command.

For Omni Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
docker run --entrypoint flexctl \
-v <path-to-registration-directory>:/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

For Omni Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v <path-to-registration-directory>:/registration:Z \
-u $UID docker.io/mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

The output should include the date of certificate expiration:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

As an example, if your current directory contains the registration file, run the following command:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=/registration/registration.yaml
```

## Renew Registration for Omni Gateway Running in Kubernetes

The following example describes a scenario where Omni Gateway is installed in a `gateway` namespace
with an `ingress` release name, and where registration is stored in the Kubernetes database.

1.  Recover the `registration.yaml` file with the following `kubectl` command:

    ```ssh
    kubectl -n gateway get secret "$(kubectl -n gateway get deployment ingress -o=jsonpath='{.spec.template.spec.volumes[?(@.name=="registration")].secret.secretName}')" -o=jsonpath='{.data.registration\.yaml}' | base64 --decode > registration.yaml
    ```

    The command stores the registration file in `./registration.yaml`.

2.  Run the `flexctl registration renew` command, as described for Docker in previous sections:

    - [Renew with Anypoint Platform User Credentials](#renew-with-user-password)

    - [Renew with Connected App Credentials](#renew-with-conn-app)

3.  Upgrade Omni Gateway with the following `helm` command:

    ```ssh
    helm get values -n gateway ingress > values.yaml \
    && helm upgrade -n gateway ingress flex-gateway/flex-gateway --wait -f values.yaml --set-file registration.content=new/registration.yaml
    ```

## Get Help with the Renewal and Verification Commands

You can run the following `help` commands for information about usage:

- Renewal

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration renew --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration renew --help
  ```

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration renew --help
  ```

- Verification

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration inspect --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration inspect --help
  ```

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration inspect --help
  ```

## Renew an Expired Registration

Attempting to run Omni Gateway with an expired certificate in Connected Mode results in the
following:

- New replicas fail to download API configurations from Anypoint Platform, thereby becoming
  unusable. Existing clusters fail to reload.

- Logs and metrics fail to upload to Anypoint Platform. Troubleshooting using Anypoint Platform is
  not possible.

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

Attempting to run Omni Gateway with an expired certificate in Local Mode results in the following:

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

If a certificate expires, you can still invoke `flexctl registration renew`, which updates the
expired certificate.

## See Also

- [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

<!-- document id=3c173bde6a654ffef838cda43c5b64f3aedf98757b61d67eea084bcbe059fd7b url=/mulesoft/current/en-us/gateway/latest/gateway-renew-certificate.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Renew Self-Managed Omni Gateway Registration

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This certificate
is generated when you register Omni Gateway in either Connected Mode or Local Mode. Updating the
certificate ensures the continued operation of your applications.

You update a certificate by renewing registration via the `flexctl registration renew` command.

- The `renew` command renews an existing Omni Gateway registration with Runtime Manager.

- For authentication, you run the `renew` command with either user credentials or with connected app
  credentials. Authentication with user credentials requires the `--username` and `--password`
  flags. Authentication with connected app credentials requires the `--client-id` and
  `--client-secret` flags.

You verify the renewal process via the `flexctl registration inspect` command.

- The `inspect` command extracts registration information you can use to verify whether the `renew`
  command was successful.

- You can also use the `inspect` command to first determine if renewing registration is actually
  required. The `inspect` command returns the certificate expiration date.

- You can verify (inspect) renewal by using the default method, or you can specify your existing
  registration file. If you run the `inspect` command without flags, the command inspects
  registration status by using the default method.

To avoid disruptions:

1.  [Download the latest version of Omni Gateway.](#before-you-begin)

2.  Renew your Omni Gateway registration.

    Choose one of two methods:

    - [Anypoint Platform User Credentials](#renew-with-user-password)

    - [Connected App Credentials](#renew-with-conn-app)

3.  Verify the success of the renewal process.

    Choose one of two methods:

    - [Default Method](#inspect-with-custom-url)

    - [Registration File](#inspect-with-reg-file)

## Before You Begin

To invoke the registration renewal `flexctl` command, download the latest version of Omni Gateway.
You don’t need to register and run this version of the gateway.

- [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

## Renew Registration with Anypoint Platform User Credentials

1.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

2.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --username=<your-username> --password=<your-password> \
     <path-to-registration-file>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your Anypoint Platform
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --username=<your-username> \
    --password=<your-password> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    > [!NOTE] Disable MFA for your Anypoint Platform account prior to running the `renew` command
    > with user credentials.

3.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

4.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

5.  Restart the Omni Gateway replica if one is already running.

## Renew Registration with Connected App Credentials

1.  If you don’t have a username or password for Anypoint Platform, you can
    [configure a connected app](https://docs.mulesoft.com/access-management/connected-apps-developers#create-a-connected-app)
    via Anypoint Access Management.

    1.  Include the following scopes:

        - Read Servers

        - Manage Servers

        - View Organization

    2.  Save the **Id** and **Secret** of the connected app you configure, then use these
        credentials in the `renew` command.

2.  Create a new directory called `flex-renew-registration` (or similar). You run the `renew`
    command in this new directory. The command creates a new registration file.

    > [!NOTE] Registration renewal fails if the `renew` command is run in a directory containing an
    > existing registration file.

3.  Use the following command:

    - Linux

    - Docker

    - Podman

    ```ssh
    flexctl registration renew --client-id=<your-client-id> --client-secret=<your-client-secret> \
     <path-to-registration-file>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file>` with the path and filename of the existing
    `registration.yaml` file.

    Use `sudo` if you encounter file permission issues when running this command.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    docker run --entrypoint flexctl \
    -v "$(pwd)":/renew \
    -v <path-to-registration-directory>:/registration \
    -u $UID mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

    As an example, if `/home/user/flex/registration.yaml` contains your current registration file,
    navigate to `/home/user/flex/` and run the following command with your connected app
    credentials:

    ```ssh
    docker run --entrypoint flexctl \
    -u $UID -v "$(pwd)":/registration  \
    mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/registration/new \
    /registration/registration.yaml
    ```

    The command creates a new registration file: `/home/user/flex/new/registration.yaml`.

    For Omni Gateway running in a container, invoke `renew` as part of the container `run` command.

    ```ssh
    podman run --entrypoint flexctl --userns=keep-id \
    -v "$(pwd)":/renew:Z \
    -v <path-to-registration-directory>:/registration:Z \
    -u $UID docker.io/mulesoft/flex-gateway \
    registration renew \
    --client-id=<your-client-id> \
    --client-secret=<your-client-secret> \
    --output-directory=/renew \
    <path-to-registration-file-in-container>
    ```

    Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.

    Replace `<path-to-registration-file-in-container>` with the path and filename of the existing
    `registration.yaml` file. You must specify the file in the container file system, which in this
    case is `/registration/registration.yaml`.

    To update environment URLs in your registration file, such as the metering environment URL, use
    the `--update-urls=true` flag.

4.  Run the command.

    The output should include the message:

    ```text
    Registration renewal completed
    ```

5.  Copy the newly created registration file to the runtime registration file location. For example:

    `/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`

6.  Restart the Omni Gateway replica if one is already running.

## Verify Registration Status with the Default Method

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect
```

Use `sudo` if you encounter file permission issues when running this command.

For Omni Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
docker exec -u $UID <container-name-or-id> flexctl registration inspect
```

For Omni Gateway running in a container, run `inspect` as part of the container `exec` command.
Replace `<container-name-or-id>` with the running container reference.

```ssh
podman exec -u $UID <container-name-or-id> flexctl registration inspect
```

The output should include the date of certificate expiration. For example:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

## Verify Registration Status with a Registration File

You can inspect a registration by extracting the information from your `registration.yaml` file.
Specify the path and filename.

To inspect a registration, run the following command:

- Linux

- Docker

- Podman

```ssh
flexctl registration inspect --file=<path-to-registration-file>
```

Use `sudo` if you encounter file permission issues when running this command.

For Omni Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
docker run --entrypoint flexctl \
-v <path-to-registration-directory>:/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

For Omni Gateway running in a container, invoke `inspect` as part of the container `run` command.

```ssh
podman run --entrypoint flexctl --userns=keep-id \
-v <path-to-registration-directory>:/registration:Z \
-u $UID docker.io/mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

The output should include the date of certificate expiration:

```text
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

As an example, if your current directory contains the registration file, run the following command:

```ssh
docker run --entrypoint flexctl \
-v "$(pwd)":/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=/registration/registration.yaml
```

## Renew Registration for Omni Gateway Running in Kubernetes

The following example describes a scenario where Omni Gateway is installed in a `gateway` namespace
with an `ingress` release name, and where registration is stored in the Kubernetes database.

1.  Recover the `registration.yaml` file with the following `kubectl` command:

    ```ssh
    kubectl -n gateway get secret "$(kubectl -n gateway get deployment ingress -o=jsonpath='{.spec.template.spec.volumes[?(@.name=="registration")].secret.secretName}')" -o=jsonpath='{.data.registration\.yaml}' | base64 --decode > registration.yaml
    ```

    The command stores the registration file in `./registration.yaml`.

2.  Run the `flexctl registration renew` command, as described for Docker in previous sections:

    - [Renew with Anypoint Platform User Credentials](#renew-with-user-password)

    - [Renew with Connected App Credentials](#renew-with-conn-app)

3.  Upgrade Omni Gateway with the following `helm` command:

    ```ssh
    helm get values -n gateway ingress > values.yaml \
    && helm upgrade -n gateway ingress flex-gateway/flex-gateway --wait -f values.yaml --set-file registration.content=new/registration.yaml
    ```

## Get Help with the Renewal and Verification Commands

You can run the following `help` commands for information about usage:

- Renewal

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration renew --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration renew --help
  ```

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration renew --help
  ```

- Verification

  - Linux

  - Docker

  - Podman

  ```ssh
  flexctl registration inspect --help
  ```

  Use `sudo` if you encounter file permission issues when running this command.

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  docker run --entrypoint flexctl mulesoft/flex-gateway registration inspect --help
  ```

  For Omni Gateway running in a container, invoke `help` as part of the container `run` command.

  ```ssh
  podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration inspect --help
  ```

## Renew an Expired Registration

Attempting to run Omni Gateway with an expired certificate in Connected Mode results in the
following:

- New replicas fail to download API configurations from Anypoint Platform, thereby becoming
  unusable. Existing clusters fail to reload.

- Logs and metrics fail to upload to Anypoint Platform. Troubleshooting using Anypoint Platform is
  not possible.

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

Attempting to run Omni Gateway with an expired certificate in Local Mode results in the following:

- Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report
  usage metrics.

If a certificate expires, you can still invoke `flexctl registration renew`, which updates the
expired certificate.

## See Also

- [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

<!-- document id=0616a12e3a72cf3222e6935d0b2f76589a464c9abc8746ae156c84673aaf0c68 url=/mulesoft/current/en-us/gateway/1.12/flex-review-prerequisites.md -->

---
product: Omni Gateway
version: 1.12
---

# Requirements and Limits for Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you download and install Anypoint Flex Gateway, review the following requirements and limits.

## Flex Gateway Requirements

### Permission Requirements

To use Flex Gateway you must have these permissions:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Permission</th><th>Ability</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Manage Servers</p></div></div></td><td><div><div><p>Create, update, and delete server and Flex Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Read Servers</p></div></div></td><td><div><div><p>View server and Flex Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Usage Viewer</p></div></div></td><td><div><div><p>View gateway metrics.</p></div></div></td><td><div><div><p>Usage permission, which can be added only by an organization administrator at the root organization level.</p></div></div></td></tr></tbody></table>

Your Anypoint Platform Admin can add these permissions in Access Management. See
[Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for more
information.

### Connected App Scope Requirements

To register Self-Managed Flex Gateway using a Connected App, the following scopes are required:

- Manage Servers

- Read Servers

- View Organization

## Managed Flex Gateway Resource Requirements

To use Managed Flex Gateway your Business Group must have at least one of these Managed Flex Gateway
resources:

- Large Managed Flex Gateways

- Small Managed Flex Gateways

Deploying an Extra Large Managed Flex Gateway requires two Large Managed Flex Gateways resources.

These resources aren’t inherited. To redistribute Managed Flex Gateway resources to a business
group, see
[Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Managed Flex Gateway Private Space Requirement

To use Managed Flex Gateway, you have created a private space in CloudHub 2.0 or have access to a
private space created by someone else.

To create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Software Requirements for Self-Managed Flex Gateway

Flex Gateway isn’t supported on Windows or in Docker running on Windows.

### Software Requirements for Kubernetes and OpenShift Deployments

Running Flex Gateway requires:

- A minimum of either Kubernetes 1.21 or OpenShift 4.8.

- Ingress v1 (stable), which requires specifying `apiVersion: networking.k8s.io/v1` as the API
  version in your configuration resources.

- A private cloud or data center.

  Or, a cloud provider such as the following:

  - Google Kubernetes Engine (GKE)

  - Amazon Elastic Kubernetes Service (Amazon EKS)

  - Azure Kubernetes Service (AKS)

- A minimum Helm version of 3.0.0 is required.

### Software Requirements for Linux Deployments

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

Flex Gateway is designed to run in cloud-native architectures. Therefore, multiple installations on
a single Linux VM aren’t supported. You can install only one gateway instance per Linux VM.

### Software Requirements for Container Deployments

Flex Gateway supports the following:

- Docker

- Podman

Additionally, Flex Gateway supports the following container orchestration services:

- Amazon Elastic Container Service (Amazon ECS)

- Azure Container Service (ACS)

- Google Cloud Run

- AWS Fargate

## Hardware Requirements for Self-Managed Flex Gateway

A single Flex Gateway can support multiple backend APIs. To support more backend APIs, you can
deploy multiple replicas or additional Flex Gateways. For information about sizing, refer to
[Resource Sizing for Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-sizing-guide).

Flex Gateway requires either an Intel or AMD-64 processor.

## Ports, IPs, and Hostnames Allowlist Requirements

For Flex Gateway to communicate with MuleSoft-managed online Anypoint Platform APIs and services,
you must add these hostnames and ports of external resources to the allowlist:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Plane</th><th>Host</th><th>Port</th><th>Mode</th><th>Description</th><th>Protocol</th></tr></thead><tbody><tr><td><p><strong>US</strong></p></td><td><p><strong>anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>arm-mcm2-service.kprod.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>logging.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>metering.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>monitoring.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange-files.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange2-asset-manager-kprod.s3.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>configuration-resolver.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>us1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Flex Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>arm-mcm2-service.kprod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>logging.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>metering.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>monitoring.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>configuration-resolver.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange-files.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange2-asset-manager-kprod-eu.s3.eu-central-1.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Flex Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Flex Gateway.</p></td><td><p>HTTPS</p></td></tr></tbody></table>

To establish connection for these endpoints, you must configure SSL passthrough:

- arm-mcm2-service.kprod.msap.io

- logging.ingestion.us-east-1.prod.cloudhub.io

- metering.ingestion.us-east-1.prod.cloudhub.io

- monitoring.ingestion.us-east-1.prod.cloudhub.io

- configuration-resolver.prod.cloudhub.io

- us1.ingest.mulesoft.com

- arm-mcm2-service.kprod-eu.msap.io

- logging.ingestion.eu-central-1.prod-eu.msap.io

- metering.ingestion.eu-central-1.prod-eu.msap.io

- eu1.ingest.mulesoft.com

- monitoring.ingestion.eu-central-1.prod-eu.msap.io

- configuration-resolver.prod-eu.msap.io

> [!NOTE] Ports 9998 and 9999 are reserved for internal processes and shouldn’t be used in
> `ApiInstance` definitions.

## Flex Gateway Limits and Performance Metrics

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>Payload</p></div></div></td><td><div><div><p>1 MB</p></div></div></td><td><div><div><p>This limit applies only to buffering the payload (such as logging the payload using message logging). If you’re not accessing the payload, the payload size has no limit.<br>Payloads that exceed this limit receive a 413 response.</p></div></div></td></tr><tr><td><div><div><p>Contracts per API</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Contracts per gateway instance</p></div></div></td><td><div><div><p>10,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Upstreams per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The 100 upstreams can consist of a combination of different routes.<br>To learn more, see <a href="https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#limits">Multiple Upstream Limits</a>.</p></div></div></td></tr><tr><td><div><div><p>Routes per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Upstreams per route</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div></div></td></tr></tbody></table>

### Managed Flex Gateway Limits and Performance Metrics

Each Managed Flex Gateway size has a limit on the number of APIs it can deploy. The platform doesn’t
allow you to exceed this limit.

<table><colgroup><col> <col></colgroup><thead><tr><th>Gateway Size</th><th>API Limit</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>500</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>500</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>50</p></div></div></td></tr></tbody></table>

Each Managed Flex Gateway size supports a maximum number of transactions per second (TPS). Exceeding
this number can increase request latency.

<table><colgroup><col> <col></colgroup><thead><tr><th>Gateway Size</th><th>TPS</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>4000</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>1500</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>50</p></div></div></td></tr></tbody></table>

### Self-Managed Flex Gateway Limits and Performance Metrics

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>APIs per Self-Managed Gateway instance</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr></tbody></table>

### See also

- [Configuring Timeouts in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-timeout)

- [Configuring Timeouts in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-timeout)

<!-- document id=ef3c64a1a6fb3a513e06484d19b10d25067f7fb19df3ff4436fed504570ddb44 url=/mulesoft/current/en-us/gateway/1.9/flex-review-prerequisites.md -->

---
product: Omni Gateway
version: 1.9
---

# Requirements and Limits for Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you download and install Anypoint Flex Gateway, review the following requirements and limits.

## Flex Gateway Requirements

### Permission Requirements

To use Flex Gateway you must have these permissions:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Permission</th><th>Ability</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Manage Servers</p></div></div></td><td><div><div><p>Create, update, and delete server and Flex Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Read Servers</p></div></div></td><td><div><div><p>View server and Flex Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Usage Viewer</p></div></div></td><td><div><div><p>View gateway metrics.</p></div></div></td><td><div><div><p>Usage permission, which can be added only by an organization administrator at the root organization level.</p></div></div></td></tr></tbody></table>

Your Anypoint Platform Admin can add these permissions in Access Management. See
[Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for more
information.

### Connected App Scope Requirements

To register Self-Managed Flex Gateway using a Connected App, the following scopes are required:

- Manage Servers

- Read Servers

- View Organization

## Managed Flex Gateway Resource Requirements

To use Managed Flex Gateway your Business Group must have at least one of these Managed Flex Gateway
resources:

- Large Managed Flex Gateways

- Small Managed Flex Gateways

These resources aren’t inherited. To redistribute Managed Flex Gateway resources to a business
group, see
[Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Managed Flex Gateway Private Space Requirement

To use Managed Flex Gateway, you have created a private space in CloudHub 2.0 or have access to a
private space created by someone else.

To create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Software Requirements for Self-Managed Flex Gateway

Flex Gateway isn’t supported on Windows or in Docker running on Windows.

### Software Requirements for Kubernetes and OpenShift Deployments

Running Flex Gateway requires:

- A minimum of either Kubernetes 1.21 or OpenShift 4.8.

- Ingress v1 (stable), which requires specifying `apiVersion: networking.k8s.io/v1` as the API
  version in your configuration resources.

- A private cloud or data center.

  Or, a cloud provider such as the following:

  - Google Kubernetes Engine (GKE)

  - Amazon Elastic Kubernetes Service (Amazon EKS)

  - Azure Kubernetes Service (AKS)

- A minimum Helm version of 3.0.0 is required.

### Software Requirements for Linux Deployments

Flex Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian (Bullseye, Bookworm)

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- SUSE Linux Enterprise (SLES 15 SP3)

- SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le)

- Ubuntu (Focal, Jammy)

Flex Gateway is designed to run in cloud-native architectures. Therefore, multiple installations on
a single Linux VM aren’t supported. You can install only one gateway instance per Linux VM.

### Software Requirements for Container Deployments

Flex Gateway supports the following:

- Docker

- Podman

Additionally, Flex Gateway supports the following container orchestration services:

- Amazon Elastic Container Service (Amazon ECS)

- Azure Container Service (ACS)

- Google Cloud Run

- AWS Fargate

## Hardware Requirements for Self-Managed Flex Gateway

A single Flex Gateway can support multiple backend APIs. To support more backend APIs, you can
deploy multiple replicas or additional Flex Gateways. For information about sizing, refer to
[Resource Sizing for Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-sizing-guide).

Flex Gateway requires either an Intel or AMD-64 processor.

## Ports, IPs, and Hostnames Allowlist Requirements

For Flex Gateway to communicate with MuleSoft-managed online Anypoint Platform APIs and services,
you must add these hostnames and ports of external resources to the allowlist:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Plane</th><th>Host</th><th>Port</th><th>Mode</th><th>Description</th><th>Protocol</th></tr></thead><tbody><tr><td><p><strong>US</strong></p></td><td><p><strong>anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>arm-mcm2-service.kprod.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>logging.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>metering.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>monitoring.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange-files.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange2-asset-manager-kprod.s3.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>configuration-resolver.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>us1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Flex Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>arm-mcm2-service.kprod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>logging.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>metering.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>monitoring.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>configuration-resolver.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange-files.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange2-asset-manager-kprod-eu.s3.eu-central-1.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Flex Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Flex Gateway.</p></td><td><p>HTTPS</p></td></tr></tbody></table>

To establish connection for these endpoints, you must configure SSL passthrough:

- arm-mcm2-service.kprod.msap.io

- logging.ingestion.us-east-1.prod.cloudhub.io

- metering.ingestion.us-east-1.prod.cloudhub.io

- monitoring.ingestion.us-east-1.prod.cloudhub.io

- configuration-resolver.prod.cloudhub.io

- us1.ingest.mulesoft.com

- arm-mcm2-service.kprod-eu.msap.io

- logging.ingestion.eu-central-1.prod-eu.msap.io

- metering.ingestion.eu-central-1.prod-eu.msap.io

- eu1.ingest.mulesoft.com

- monitoring.ingestion.eu-central-1.prod-eu.msap.io

- configuration-resolver.prod-eu.msap.io

> [!NOTE] Port 9998 is reserved for internal processes, and should not be used in `ApiInstance`
> definitions.

## Flex Gateway Limits

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>Payload</p></div></div></td><td><div><div><p>1 MB</p></div></div></td><td><div><div><p>This limit applies only to buffering the payload (such as logging the payload using message logging). If you’re not accessing the payload, the payload size has no limit.<br>Payloads that exceed this limit receive a 413 response.</p></div></div></td></tr><tr><td><div><div><p>Contracts per API</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Contracts per gateway instance</p></div></div></td><td><div><div><p>10,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Upstreams per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The 100 upstreams can consist of a combination of different routes.<br>To learn more, see <a href="https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#limits">Multiple Upstream Limits</a>.</p></div></div></td></tr><tr><td><div><div><p>Routes per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Upstreams per route</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div></div></td></tr></tbody></table>

### Managed Flex Gateway Limits

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>APIs per Large Managed Gateway instance</p></div></div></td><td><div><div><p>500</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>APIs per Small Managed Gateway instance</p></div></div></td><td><div><div><p>50</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Requests per second for Large Managed Gateway</p></div></div></td><td><div><div><p>500</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Requests per second for Small Managed Gateway</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div></div></td></tr></tbody></table>

### Self-Managed Flex Gateway Limits

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>APIs per Self-Managed Gateway instance</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr></tbody></table>

## Flex Gateway Environment Variables

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Environment Variable</th><th>Default Value</th><th>Function</th></tr></thead><tbody><tr><td><div><div><p>FLEX_CONNECTION_IDLE_TIMEOUT_SECONDS</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Maximum number of seconds a connection can be idle before it times out.</p></div></div></td></tr><tr><td><div><div><p>FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES</p></div></div></td><td><div><div><p>1048576 (1 MB)</p></div></div></td><td><div><div><p>Maximum size, in bytes, of read and write buffers for new connections.</p></div></div></td></tr><tr><td><div><div><p>FLEX_ENVOY_HEADERS_ENABLED</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Allows (<code>true</code>) or removes (<code>false</code>) Envoy headers from requests.</p></div></div></td></tr><tr><td><div><div><p>FLEX_STREAM_IDLE_TIMEOUT_SECONDS</p></div></div></td><td><div><div><p>300</p></div></div></td><td><div><div><p>Maximum number of seconds a stream can remain idle without receiving any data in either the inbound (client to Flex Gateway) or outbound (Flex Gateway to upstream service) direction.</p></div></div></td></tr><tr><td><div><div><p>FLEX_UPSTREAM_CONNECTION_IDLE_TIMEOUT_SECONDS</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Maximum number of seconds a stream between Flex Gateway and the upstream service can remain idle between requests.</p></div></div></td></tr><tr><td><div><div><p>FLEX_UPSTREAM_RESPONSE_TIMEOUT_SECONDS</p></div></div></td><td><div><div><p>15</p></div></div></td><td><div><div><p>Maximum number of seconds a Flex Gateway waits for a response from an upstream service.</p></div></div></td></tr></tbody></table>

### See also

- [Configuring Timeouts in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-timeout)

- [Configuring Timeouts in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-timeout)

<!-- document id=8eac50e32328d21cf9d609350367510a6b3542484d9ea6db4d8a30944be809e9 url=/mulesoft/current/en-us/gateway/1.13/review-prerequisites.md -->

---
product: Omni Gateway
version: 1.13
---

# Requirements and Limits for Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you download and install Omni Gateway, review the following requirements and limits.

## Omni Gateway Requirements

### Permission Requirements

To use Omni Gateway you must have these permissions:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Permission</th><th>Ability</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Manage Servers</p></div></div></td><td><div><div><p>Create, update, and delete server and Omni Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Read Servers</p></div></div></td><td><div><div><p>View server and Omni Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Usage Viewer</p></div></div></td><td><div><div><p>View gateway metrics.</p></div></div></td><td><div><div><p>Usage permission, which can be added only by an organization administrator at the root organization level.</p></div></div></td></tr></tbody></table>

Your Anypoint Platform Admin can add these permissions in Access Management. See
[Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for more
information.

### Connected App Scope Requirements

To register Self-Managed Omni Gateway using a Connected App, the following scopes are required:

- Manage Servers

- Read Servers

- View Organization

## Managed Omni Gateway Resource Requirements

To use Managed Omni Gateway your Business Group must have at least one of these Managed Omni Gateway
resources:

- Large Managed Omni Gateways

- Small Managed Omni Gateways

Deploying an Extra Large Managed Omni Gateway requires two Large Managed Omni Gateways resources.

These resources aren’t inherited. To redistribute Managed Omni Gateway resources to a business
group, see
[Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Managed Omni Gateway Private Space Requirement

To use Managed Omni Gateway, you have created a private space in CloudHub 2.0 or have access to a
private space created by someone else.

To create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Software Requirements for Self-Managed Omni Gateway

Omni Gateway isn’t supported on Windows or in Docker running on Windows.

### Software Requirements for Kubernetes and OpenShift Deployments

Running Omni Gateway requires:

- A minimum of either Kubernetes 1.21 or OpenShift 4.8.

- Ingress v1 (stable), which requires specifying `apiVersion: networking.k8s.io/v1` as the API
  version in your configuration resources.

- A private cloud or data center.

  Or, a cloud provider such as the following:

  - Google Kubernetes Engine (GKE)

  - Amazon Elastic Kubernetes Service (Amazon EKS)

  - Azure Kubernetes Service (AKS)

- A minimum Helm version of 3.0.0 is required.

### Software Requirements for Linux Deployments

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

Omni Gateway is designed to run in cloud-native architectures. Therefore, multiple installations on
a single Linux VM aren’t supported. You can install only one gateway instance per Linux VM.

### Software Requirements for Container Deployments

Omni Gateway supports the following:

- Docker

- Podman

Additionally, Omni Gateway supports the following container orchestration services:

- Amazon Elastic Container Service (Amazon ECS)

- Azure Container Service (ACS)

- Google Cloud Run

- AWS Fargate

## Hardware Requirements for Self-Managed Omni Gateway

A single Omni Gateway can support multiple backend APIs. To support more backend APIs, you can
deploy multiple replicas or additional Omni Gateways. For information about sizing, refer to
[Resource Sizing for Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/sizing-guide).

Omni Gateway requires either an Intel or AMD-64 processor.

## Ports, IPs, and Hostnames Allowlist Requirements

For Omni Gateway to communicate with MuleSoft-managed online Anypoint Platform APIs and services,
you must add these hostnames and ports of external resources to the allowlist:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Plane</th><th>Host</th><th>Port</th><th>Mode</th><th>Description</th><th>Protocol</th></tr></thead><tbody><tr><td><p><strong>US</strong></p></td><td><p><strong>anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>arm-mcm2-service.kprod.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>logging.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>metering.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>monitoring.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange-files.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange2-asset-manager-kprod.s3.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>configuration-resolver.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>us1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Omni Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>arm-mcm2-service.kprod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>logging.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>metering.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>monitoring.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>configuration-resolver.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange-files.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange2-asset-manager-kprod-eu.s3.eu-central-1.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Omni Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Omni Gateway.</p></td><td><p>HTTPS</p></td></tr></tbody></table>

To establish connection for these endpoints, you must configure SSL passthrough:

- arm-mcm2-service.kprod.msap.io

- logging.ingestion.us-east-1.prod.cloudhub.io

- metering.ingestion.us-east-1.prod.cloudhub.io

- monitoring.ingestion.us-east-1.prod.cloudhub.io

- configuration-resolver.prod.cloudhub.io

- us1.ingest.mulesoft.com

- arm-mcm2-service.kprod-eu.msap.io

- logging.ingestion.eu-central-1.prod-eu.msap.io

- metering.ingestion.eu-central-1.prod-eu.msap.io

- eu1.ingest.mulesoft.com

- monitoring.ingestion.eu-central-1.prod-eu.msap.io

- configuration-resolver.prod-eu.msap.io

> [!NOTE] Ports 9998 and 9999 are reserved for internal processes and shouldn’t be used in
> `ApiInstance` definitions.

## Omni Gateway Limits and Performance Metrics

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>Payload</p></div></div></td><td><div><div><p>1 MB</p></div></div></td><td><div><div><p>This limit applies only to buffering the payload (such as logging the payload using message logging). If you’re not accessing the payload, the payload size has no limit.<br>Payloads that exceed this limit receive a 413 response.</p></div></div></td></tr><tr><td><div><div><p>Contracts per API</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Contracts per gateway instance</p></div></div></td><td><div><div><p>10,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Upstreams per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>Each API supports 100 upstreams. The 100 upstreams can consist of a combination of different routes.</p></div></div></td></tr><tr><td><div><div><p>Routes per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>Each API supports 100 routes.</p></div></div></td></tr><tr><td><div><div><p>Upstreams per route</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Headers per route rule</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div></div></td></tr></tbody></table>

To configure multiple upstream services in Connected Mode, see
[Multiple Upstream Services for Omni Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

### Managed Omni Gateway Limits and Performance Metrics

Each Managed Omni Gateway size has a limit on the number of APIs it can deploy. The platform doesn’t
allow you to exceed this limit.

<table><colgroup><col> <col></colgroup><thead><tr><th>Gateway Size</th><th>API Limit</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>500</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>500</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>50</p></div></div></td></tr></tbody></table>

Each Managed Omni Gateway size supports a maximum number of transactions per second (TPS). Exceeding
this number can increase request latency.

<table><colgroup><col> <col></colgroup><thead><tr><th>Gateway Size</th><th>TPS</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>4000</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>1500</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>50</p></div></div></td></tr></tbody></table>

Each Managed Omni Gateway size is highly available. All sizes run at least two replicas distributed
across different availability zones. Large and extra large gateways autoscale, adding replicas based
on CPU usage.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Gateway Size</th><th>Highly Available</th><th>Autoscales</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

For more information about how Managed Omni Gateway handles high availability and autoscaling, see
[Managed Omni Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-managed-dr-ha).

### Self-Managed Omni Gateway Limits and Performance Metrics

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>APIs per Self-Managed Gateway instance</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr></tbody></table>

### See also

- [Configuring Timeouts in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-timeout)

- [Configuring Timeouts in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-timeout)

<!-- document id=04c111e7a2d0c79f8f4e672f12fb051e80ca6ed9d23b80681f9eae0e6b5d08c8 url=/mulesoft/current/en-us/gateway/latest/review-prerequisites.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Requirements and Limits for Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before you download and install Omni Gateway, review the following requirements and limits.

## Omni Gateway Requirements

### Permission Requirements

To use Omni Gateway you must have these permissions:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Permission</th><th>Ability</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Manage Servers</p></div></div></td><td><div><div><p>Create, update, and delete server and Omni Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Read Servers</p></div></div></td><td><div><div><p>View server and Omni Gateway resources.</p></div></div></td><td><div><div><p>Runtime Manager permission, which is assigned to a specific environment in a Business Group.</p></div></div></td></tr><tr><td><div><div><p>Usage Viewer</p></div></div></td><td><div><div><p>View gateway metrics.</p></div></div></td><td><div><div><p>Usage permission, which can be added only by an organization administrator at the root organization level.</p></div></div></td></tr></tbody></table>

Your Anypoint Platform Admin can add these permissions in Access Management. See
[Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) for more
information.

### Connected App Scope Requirements

To register Self-Managed Omni Gateway using a Connected App, the following scopes are required:

- Manage Servers

- Read Servers

- View Organization

## Managed Omni Gateway Resource Requirements

To use Managed Omni Gateway your Business Group must have at least one of these Managed Omni Gateway
resources:

- Large Managed Omni Gateways

- Small Managed Omni Gateways

Deploying an Extra Large Managed Omni Gateway requires two Large Managed Omni Gateways resources.

These resources aren’t inherited. To redistribute Managed Omni Gateway resources to a business
group, see
[Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Managed Omni Gateway Private Space Requirement

To use Managed Omni Gateway, you have created a private space in CloudHub 2.0 or have access to a
private space created by someone else.

To create a private space, see [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure).

## Software Requirements for Self-Managed Omni Gateway

Omni Gateway isn’t supported on Windows or in Docker running on Windows.

### Software Requirements for Kubernetes and OpenShift Deployments

Running Omni Gateway requires:

- A minimum of either Kubernetes 1.21 or OpenShift 4.8.

- Ingress v1 (stable), which requires specifying `apiVersion: networking.k8s.io/v1` as the API
  version in your configuration resources.

- A private cloud or data center.

  Or, a cloud provider such as the following:

  - Google Kubernetes Engine (GKE)

  - Amazon Elastic Kubernetes Service (Amazon EKS)

  - Azure Kubernetes Service (AKS)

- A minimum Helm version of 3.0.0 is required.

### Software Requirements for Linux Deployments

Omni Gateway runs on the following Long Term Support (LTS) versions of Linux:

- Amazon Linux 2023

- CentOS 8

- Debian Bookworm

- Red Hat Enterprise Linux (9)

- Red Hat Enterprise Linux (9) on IBM Power (ppc64le)

- Ubuntu Jammy

Omni Gateway is designed to run in cloud-native architectures. Therefore, multiple installations on
a single Linux VM aren’t supported. You can install only one gateway instance per Linux VM.

### Software Requirements for Container Deployments

Omni Gateway supports the following:

- Docker

- Podman

Additionally, Omni Gateway supports the following container orchestration services:

- Amazon Elastic Container Service (Amazon ECS)

- Azure Container Service (ACS)

- Google Cloud Run

- AWS Fargate

## Hardware Requirements for Self-Managed Omni Gateway

A single Omni Gateway can support multiple backend APIs. To support more backend APIs, you can
deploy multiple replicas or additional Omni Gateways. For information about sizing, refer to
[Resource Sizing for Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/sizing-guide).

Omni Gateway requires either an Intel or AMD-64 processor.

## Ports, IPs, and Hostnames Allowlist Requirements

For Omni Gateway to communicate with MuleSoft-managed online Anypoint Platform APIs and services,
you must add these hostnames and ports of external resources to the allowlist:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Plane</th><th>Host</th><th>Port</th><th>Mode</th><th>Description</th><th>Protocol</th></tr></thead><tbody><tr><td><p><strong>US</strong></p></td><td><p><strong>anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>arm-mcm2-service.kprod.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>logging.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>metering.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>monitoring.ingestion.us-east-1.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange-files.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>exchange2-asset-manager-kprod.s3.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>configuration-resolver.prod.cloudhub.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>us1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>US</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Omni Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to connect with the control plane, push internal metrics, and download custom policy binaries.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>arm-mcm2-service.kprod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to communicate with the transport layer.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>logging.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>metering.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>eu1.ingest.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>monitoring.ingestion.eu-central-1.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to send analytics data to the control plane.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>configuration-resolver.prod-eu.msap.io</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>mTLS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange-files.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>exchange2-asset-manager-kprod-eu.s3.eu-central-1.amazonaws.com</strong></p></td><td><p>443</p></td><td><p>Connected</p></td><td><p>Required to download policies.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Omni Gateway.</p></td><td><p>HTTPS</p></td></tr><tr><td><p><strong>EU</strong></p></td><td><p><strong>flex-packages.eu1.anypoint.mulesoft.com</strong></p></td><td><p>443</p></td><td><p>Both</p></td><td><p>Required to download and install Omni Gateway.</p></td><td><p>HTTPS</p></td></tr></tbody></table>

To establish connection for these endpoints, you must configure SSL passthrough:

- arm-mcm2-service.kprod.msap.io

- logging.ingestion.us-east-1.prod.cloudhub.io

- metering.ingestion.us-east-1.prod.cloudhub.io

- monitoring.ingestion.us-east-1.prod.cloudhub.io

- configuration-resolver.prod.cloudhub.io

- us1.ingest.mulesoft.com

- arm-mcm2-service.kprod-eu.msap.io

- logging.ingestion.eu-central-1.prod-eu.msap.io

- metering.ingestion.eu-central-1.prod-eu.msap.io

- eu1.ingest.mulesoft.com

- monitoring.ingestion.eu-central-1.prod-eu.msap.io

- configuration-resolver.prod-eu.msap.io

> [!NOTE] Ports 9998 and 9999 are reserved for internal processes and shouldn’t be used in
> `ApiInstance` definitions.

## Omni Gateway Limits and Performance Metrics

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>Payload</p></div></div></td><td><div><div><p>1 MB</p></div></div></td><td><div><div><p>This limit applies only to buffering the payload (such as logging the payload using message logging, MCP support, and Agent Connection Telemetry policy). If you don’t access the payload, the payload size has no limit.<br>Request payloads that exceed this limit receive a 413 response.<br>For response payloads that exceed this limit, Omni Gateway closes the connection instead of returning a 413 response.</p></div></div></td></tr><tr><td><div><div><p>Contracts per API</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Contracts per gateway instance</p></div></div></td><td><div><div><p>10,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr><tr><td><div><div><p>Upstreams per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>Each API supports 100 upstreams. The 100 upstreams can consist of a combination of different routes.</p></div></div></td></tr><tr><td><div><div><p>Routes per API</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>Each API supports 100 routes.</p></div></div></td></tr><tr><td><div><div><p>Upstreams per route</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p>Headers per route rule</p></div></div></td><td><div><div><p>10</p></div></div></td><td><div></div></td></tr></tbody></table>

To configure multiple upstream services in Connected Mode, see
[Multiple Upstream Services for Omni Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

### Managed Omni Gateway Limits and Performance Metrics

Each Managed Omni Gateway size has a limit on the number of APIs it can deploy. The platform doesn’t
allow you to exceed this limit.

<table><colgroup><col> <col></colgroup><thead><tr><th>Gateway Size</th><th>API Limit</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>500</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>500</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>50</p></div></div></td></tr></tbody></table>

Each Managed Omni Gateway size supports a maximum number of transactions per second (TPS). Exceeding
this number can increase request latency.

<table><colgroup><col> <col></colgroup><thead><tr><th>Gateway Size</th><th>TPS</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>4000</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>1500</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>50</p></div></div></td></tr></tbody></table>

Each Managed Omni Gateway size is highly available. All sizes run at least two replicas distributed
across different availability zones. Large and extra large gateways autoscale, adding replicas based
on CPU usage.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Gateway Size</th><th>Highly Available</th><th>Autoscales</th></tr></thead><tbody><tr><td><div><div><p>Extra Large Managed Gateway</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Large Managed Gateway</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Small Managed Gateway</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

For more information about how Managed Omni Gateway handles high availability and autoscaling, see
[Managed Omni Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/latest/gateway-architecture-managed-dr-ha).

### Self-Managed Omni Gateway Limits and Performance Metrics

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><div><div><p>Request header</p></div></div></td><td><div><div><p>60 KB</p></div></div></td><td><div><div><p>Requests that exceed this limit receive a <code>431</code> response.</p></div></div></td></tr><tr><td><div><div><p>APIs per Self-Managed Gateway instance</p></div></div></td><td><div><div><p>1,000</p></div></div></td><td><div><div><p>Exceeding this limit isn’t supported but doesn’t cause errors.</p></div></div></td></tr></tbody></table>

### See also

- [Configuring Timeouts in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-timeout)

- [Configuring Timeouts in Local Mode](https://docs.mulesoft.com/gateway/latest/local-timeout)

<!-- document id=22793c2c0fc73187eb68bc2ce9196dc9d3ecb30d1d82f7b9bcffc8f642082261 url=/mulesoft/current/en-us/gateway/latest/troubleshoot-reset-cache.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Resetting the Control Node Cache with the CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

If the control node cache becomes corrupted or you encounter other critical issues that affect the
integrity of the cache, use the `flexctl reset` CLI to erase the cache state.

Resetting the control node cache can’t be undone. Use `flexctl reset` only to recover from data
corruption or other critical cache issues.

The command deletes only the control node’s data from the configured shared storage. When the shared
storage is Redis, other keys in the same Redis instance, such as those used by policies, aren’t
deleted.

> [!NOTE] To run `flexctl reset` for Linux deployments, either add the user to the `flex` user group
> or run `flexctl reset` with the `sudo` command. To learn more, see
> [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/latest/troubleshoot-linux-permissions).

## Run the CLI

1.  Run the following command:

    ```ssh
    flexctl reset
    ```

    To run the command in a container without entering it, run:

    ```ssh
    docker exec -it flex-gateway flexctl reset
    ```

2.  When prompted to confirm, type `yes`. Any other input cancels the operation.

    If the reset succeeds, the CLI returns the following message:

    Storage was reset successfully. You can restart flex now!

3.  Restart Omni Gateway.

## Change the Admin API Address

By default, `flexctl reset` connects to the gateway’s Admin API through the Unix socket
`/var/tmp/mulesoft/flex-gateway/flex-agent-status-api.sock`. To use a different Admin API address,
use the `--flex-admin-api-url` flag:

```ssh
flexctl reset --flex-admin-api-url <ADMIN_API_URL>
```

## See Also

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/latest/troubleshoot-admin-api)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=0b0eec0627ed9b45e5e3a5f31a55b2c32eeeafc17f387ca47190fd5a13511c36 url=/mulesoft/current/en-us/gateway/1.12/flex-sizing-guide.md -->

---
product: Omni Gateway
version: 1.12
---

# Resource Sizing for Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before getting started with Flex Gateway, analyze and choose your configuration to obtain the best
performance and auto-scaling rate.

When assigning resources for a replica node, consider:

- Number of APIs

- Amount of memory the node needs

- Processing power for the node

- Number of policies in each API

- Amount of traffic each node handles

- Amount of time the node takes to answer the request (latency)

- Type of traffic the node handles, and within the traffic:

  - The number of requests per second (RPS) the node handles

  - Size of each request (bytes)

## Resources

The following table describes the resources you must allocate to your replica node according to your
environment:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>CPU</th><th>RAM</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>1-2 cores</p></td><td><p>2-4 GB</p></td></tr><tr><td><p>Medium</p></td><td><p>2-4 cores</p></td><td><p>4-8 GB</p></td></tr><tr><td><p>Large</p></td><td><p>8-16 cores</p></td><td><p>16-32 GB</p></td></tr></tbody></table>

> [!NOTE] For IBM Power10 deployments, allocate 5-16 CPU cores for a "Large" node.

> [!NOTE] Nodes belonging to a cluster must be of the same size.

## Cluster Size

The following table describes appropriate node and cluster sizes:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>Number of APIs</th><th>Number of Policies</th><th>Expected Latency</th><th>Expected Throughput</th><th>Target Environment</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>&lt; 100</p></td><td><p>4</p></td><td><p>&lt; 30 ms</p></td><td><p>&lt; 500 RPS</p></td><td><p>Dev/test cluster</p></td></tr><tr><td><p>Medium</p></td><td><p>&lt; 500</p></td><td><p>4</p></td><td><p>&lt; 20 ms</p></td><td><p>&lt; 2500 RPS</p></td><td><p>Production cluster</p></td></tr><tr><td><p>Large</p></td><td><p>&gt; 500</p></td><td><p>4</p></td><td><p>&lt; 10 ms</p></td><td><p>&lt; 10000 RPS</p></td><td><p>Mission-critical clusters</p></td></tr></tbody></table>

These sizing figures are per node. API configurations replicate to all nodes in the cluster. For
example, for 10 APIs deployed each with three policies, the 10 APIs and their policies are deployed
to each node in the cluster.

The traffic is distributed across all nodes in the cluster. A small cluster node supports up to 500
RPS, but if the cluster has two nodes then the total traffic that the cluster allows is 1000 RPS
(500 RPS for each node). Exceeding the recommended traffic per node eventually causes increased CPU
usage. To avoid this issue, you must increase the size of all nodes in the cluster or scale
horizontally.

High CPU usage can lead to increased latency. In such a case, proceed with horizontal scaling or
increase the node size.

High memory consumption can lead to out-of-memory errors. To solve this issue, increase the memory
allocation or the node size. Horizontal scaling might not help solve issues in this situation. You
must increase memory first, and scale horizontally later.

These guidelines are for a cluster with an average request size of 1 KB and four policies
implemented. Adjust your parameters depending on your use case.

The most commonly used out-of-the-box policies are:

- Message logging

- Rate limiting

- JWT validation

- Header injection

Using TLS affects the response time and the process consumption.

<!-- document id=060069aed02545d1390e2f362cf8bf725b875ab6b1a7349da9d1ac75b26ddbc9 url=/mulesoft/current/en-us/gateway/1.9/flex-sizing-guide.md -->

---
product: Omni Gateway
version: 1.9
---

# Resource Sizing for Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before getting started with Flex Gateway, analyze and choose your configuration to obtain the best
performance and auto-scaling rate.

When assigning resources for a replica node, consider:

- Number of APIs

- Amount of memory the node needs

- Processing power for the node

- Number of policies in each API

- Amount of traffic each node handles

- Amount of time the node takes to answer the request (latency)

- Type of traffic the node handles, and within the traffic:

  - The number of requests per second (RPS) the node handles

  - Size of each request (bytes)

## Resources

The following table describes the resources you must allocate to your replica node according to your
environment:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>CPU</th><th>RAM</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>1-2 cores</p></td><td><p>2-4 GB</p></td></tr><tr><td><p>Medium</p></td><td><p>2-4 cores</p></td><td><p>4-8 GB</p></td></tr><tr><td><p>Large</p></td><td><p>8-16 cores</p></td><td><p>16-32 GB</p></td></tr></tbody></table>

> [!NOTE] For IBM Power10 deployments, allocate 5-16 CPU cores for a "Large" node.

> [!NOTE] Nodes belonging to a cluster must be of the same size.

## Cluster Size

The following table describes appropriate node and cluster sizes:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>Number of APIs</th><th>Number of Policies</th><th>Expected Latency</th><th>Expected Throughput</th><th>Target Environment</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>&lt; 100</p></td><td><p>4</p></td><td><p>&lt; 30 ms</p></td><td><p>&lt; 500 RPS</p></td><td><p>Dev/test cluster</p></td></tr><tr><td><p>Medium</p></td><td><p>&lt; 500</p></td><td><p>4</p></td><td><p>&lt; 20 ms</p></td><td><p>&lt; 2500 RPS</p></td><td><p>Production cluster</p></td></tr><tr><td><p>Large</p></td><td><p>&gt; 500</p></td><td><p>4</p></td><td><p>&lt; 10 ms</p></td><td><p>&lt; 10000 RPS</p></td><td><p>Mission-critical clusters</p></td></tr></tbody></table>

These sizing figures are per node. API configurations replicate to all nodes in the cluster. For
example, for 10 APIs deployed each with three policies, the 10 APIs and their policies are deployed
to each node in the cluster.

The traffic is distributed across all nodes in the cluster. A small cluster node supports up to 500
RPS, but if the cluster has two nodes then the total traffic that the cluster allows is 1000 RPS
(500 RPS for each node). Exceeding the recommended traffic per node eventually causes increased CPU
usage. To avoid this issue, you must increase the size of all nodes in the cluster or scale
horizontally.

High CPU usage can lead to increased latency. In such a case, proceed with horizontal scaling or
increase the node size.

High memory consumption can lead to out-of-memory errors. To solve this issue, increase the memory
allocation or the node size. Horizontal scaling might not help solve issues in this situation. You
must increase memory first, and scale horizontally later.

These guidelines are for a cluster with an average request size of 1 KB and four policies
implemented. Adjust your parameters depending on your use case.

The most commonly used out-of-the-box policies are:

- Message logging

- Rate limiting

- JWT validation

- Header injection

Using TLS affects the response time and the process consumption.

<!-- document id=8d03586402a1d1a29487437cac957cbb030782b31a54697f18dff13416f4e635 url=/mulesoft/current/en-us/gateway/1.13/sizing-guide.md -->

---
product: Omni Gateway
version: 1.13
---

# Resource Sizing for Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before getting started with Omni Gateway, analyze and choose your configuration to obtain the best
performance and auto-scaling rate.

When assigning resources for a replica node, consider:

- Number of APIs

- Amount of memory the node needs

- Processing power for the node

- Number of policies in each API

- Amount of traffic each node handles

- Amount of time the node takes to answer the request (latency)

- Type of traffic the node handles, and within the traffic:

  - The number of requests per second (RPS) the node handles

  - Size of each request (bytes)

## Resources

The following table describes the resources you must allocate to your replica node according to your
environment:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>CPU</th><th>RAM</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>1-2 cores</p></td><td><p>2-4 GB</p></td></tr><tr><td><p>Medium</p></td><td><p>2-4 cores</p></td><td><p>4-8 GB</p></td></tr><tr><td><p>Large</p></td><td><p>8-16 cores</p></td><td><p>16-32 GB</p></td></tr></tbody></table>

> [!NOTE] For IBM Power10 deployments, allocate 5-16 CPU cores for a "Large" node.

> [!NOTE] Nodes belonging to a cluster must be of the same size.

## Cluster Size

The following table describes appropriate node and cluster sizes:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>Number of APIs</th><th>Number of Policies</th><th>Expected Latency</th><th>Expected Throughput</th><th>Target Environment</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>&lt; 100</p></td><td><p>4</p></td><td><p>&lt; 30 ms</p></td><td><p>&lt; 500 RPS</p></td><td><p>Dev/test cluster</p></td></tr><tr><td><p>Medium</p></td><td><p>&lt; 500</p></td><td><p>4</p></td><td><p>&lt; 20 ms</p></td><td><p>&lt; 2500 RPS</p></td><td><p>Production cluster</p></td></tr><tr><td><p>Large</p></td><td><p>&gt; 500</p></td><td><p>4</p></td><td><p>&lt; 10 ms</p></td><td><p>&lt; 10000 RPS</p></td><td><p>Mission-critical clusters</p></td></tr></tbody></table>

These sizing figures are per node. API configurations replicate to all nodes in the cluster. For
example, for 10 APIs deployed each with three policies, the 10 APIs and their policies are deployed
to each node in the cluster.

The traffic is distributed across all nodes in the cluster. A small cluster node supports up to 500
RPS, but if the cluster has two nodes then the total traffic that the cluster allows is 1000 RPS
(500 RPS for each node). Exceeding the recommended traffic per node eventually causes increased CPU
usage. To avoid this issue, you must increase the size of all nodes in the cluster or scale
horizontally.

High CPU usage can lead to increased latency. In such a case, proceed with horizontal scaling or
increase the node size.

High memory consumption can lead to out-of-memory errors. To solve this issue, increase the memory
allocation or the node size. Horizontal scaling might not help solve issues in this situation. You
must increase memory first, and scale horizontally later.

These guidelines are for a cluster with an average request size of 1 KB and four policies
implemented. Adjust your parameters depending on your use case.

The most commonly used out-of-the-box policies are:

- Message logging

- Rate limiting

- JWT validation

- Header injection

Using TLS affects the response time and the process consumption.

<!-- document id=67b514d49f190a2673d46b3458d7528d0ff396f7378eeddf90441e5047e8687e url=/mulesoft/current/en-us/gateway/latest/sizing-guide.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Resource Sizing for Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Before getting started with Omni Gateway, analyze and choose your configuration to obtain the best
performance and auto-scaling rate.

When assigning resources for a replica node, consider:

- Number of APIs

- Amount of memory the node needs

- Processing power for the node

- Number of policies in each API

- Amount of traffic each node handles

- Amount of time the node takes to answer the request (latency)

- Type of traffic the node handles, and within the traffic:

  - The number of requests per second (RPS) the node handles

  - Size of each request (bytes)

## Resources

The following table describes the resources you must allocate to your replica node according to your
environment:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>CPU</th><th>RAM</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>1-2 cores</p></td><td><p>2-4 GB</p></td></tr><tr><td><p>Medium</p></td><td><p>2-4 cores</p></td><td><p>4-8 GB</p></td></tr><tr><td><p>Large</p></td><td><p>8-16 cores</p></td><td><p>16-32 GB</p></td></tr></tbody></table>

> [!NOTE] For IBM Power10 deployments, allocate 5-16 CPU cores for a "Large" node.

> [!NOTE] Nodes belonging to a cluster must be of the same size.

## Cluster Size

The following table describes appropriate node and cluster sizes:

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Node Size</th><th>Number of APIs</th><th>Number of Policies</th><th>Expected Latency</th><th>Expected Throughput</th><th>Target Environment</th></tr></thead><tbody><tr><td><p>Small</p></td><td><p>&lt; 100</p></td><td><p>4</p></td><td><p>&lt; 30 ms</p></td><td><p>&lt; 500 RPS</p></td><td><p>Dev/test cluster</p></td></tr><tr><td><p>Medium</p></td><td><p>&lt; 500</p></td><td><p>4</p></td><td><p>&lt; 20 ms</p></td><td><p>&lt; 2500 RPS</p></td><td><p>Production cluster</p></td></tr><tr><td><p>Large</p></td><td><p>&gt; 500</p></td><td><p>4</p></td><td><p>&lt; 10 ms</p></td><td><p>&lt; 10000 RPS</p></td><td><p>Mission-critical clusters</p></td></tr></tbody></table>

These sizing figures are per node. API configurations replicate to all nodes in the cluster. For
example, for 10 APIs deployed each with three policies, the 10 APIs and their policies are deployed
to each node in the cluster.

The traffic is distributed across all nodes in the cluster. A small cluster node supports up to 500
RPS, but if the cluster has two nodes then the total traffic that the cluster allows is 1000 RPS
(500 RPS for each node). Exceeding the recommended traffic per node eventually causes increased CPU
usage. To avoid this issue, you must increase the size of all nodes in the cluster or scale
horizontally.

High CPU usage can lead to increased latency. In such a case, proceed with horizontal scaling or
increase the node size.

High memory consumption can lead to out-of-memory errors. To solve this issue, increase the memory
allocation or the node size. Horizontal scaling might not help solve issues in this situation. You
must increase memory first, and scale horizontally later.

These guidelines are for a cluster with an average request size of 1 KB and four policies
implemented. Adjust your parameters depending on your use case.

The most commonly used out-of-the-box policies are:

- Message logging

- Rate limiting

- JWT validation

- Header injection

Using TLS affects the response time and the process consumption.

<!-- document id=25288a6d4815be0cec8fa686459636b0914f6681a76db530bdfa3dab4786ff8d url=/mulesoft/current/en-us/gateway/1.12/policies-resource-level-overview.md -->

---
product: Omni Gateway
version: 1.12
keywords: policy, custom, ootb, offline, resource level
---

# Resource-Level Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Unless otherwise configured, policies are by default applied to the entire API. However, you can
implement an additional level of policy granularity, one in which access is controlled based on a
criteria. Policies with this granularity are called _resource-level policies_.

At the resource level of granularity, policies are applied to only those requests that match the
criteria. All policies, except the Cross-Origin Resource Sharing (CORS) policy, are resource-level.

For Flex Gateway running in Connected Mode, you configure resource-level policies in API Manager.

For information about configuring resource-level policies for Flex Gateway running in Local Mode,
refer to
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.12/flex-local-secure-api-with-auto-policy).

<!-- document id=299e84983aeba8b26ae7d82c8974e87bb0c2cc442fbba288283bc4a13fd89ced url=/mulesoft/current/en-us/gateway/1.13/policies-resource-level-overview.md -->

---
product: Omni Gateway
version: 1.13
keywords: policy, custom, ootb, offline, resource level
---

# Resource-Level Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Unless otherwise configured, policies are by default applied to the entire API. However, you can
implement an additional level of policy granularity, one in which access is controlled based on a
criteria. Policies with this granularity are called _resource-level policies_.

At the resource level of granularity, policies are applied to only those requests that match the
criteria. All policies, except the Cross-Origin Resource Sharing (CORS) policy, are resource-level.

For Omni Gateway running in Connected Mode, you configure resource-level policies in API Manager.

For information about configuring resource-level policies for Omni Gateway running in Local Mode,
refer to [Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.13/local-secure-api-with-auto-policy).

<!-- document id=24c903040c0f87294f639372d5a6e886c49372a7cef3d5bf2af03d140c95e474 url=/mulesoft/current/en-us/gateway/1.9/policies-resource-level-overview.md -->

---
product: Omni Gateway
version: 1.9
keywords: policy, custom, ootb, offline, resource level
---

# Resource-Level Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Unless otherwise configured, policies are by default applied to the entire API. However, you can
implement an additional level of policy granularity, one in which access is controlled based on a
criteria. Policies with this granularity are called _resource-level policies_.

At the resource level of granularity, policies are applied to only those requests that match the
criteria. All policies, except the Cross-Origin Resource Sharing (CORS) policy, are resource-level.

For Flex Gateway running in Connected Mode, you configure resource-level policies in API Manager.

For information about configuring resource-level policies for Flex Gateway running in Local Mode,
refer to
[Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/1.9/flex-local-secure-api-with-auto-policy).

<!-- document id=e36b154ef0cb583e25ebbdd5c844a2b674205c42434ff53d99c80a9130fe2bbb url=/mulesoft/current/en-us/gateway/latest/policies-resource-level-overview.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: policy, custom, ootb, offline, resource level
---

# Resource-Level Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Unless otherwise configured, policies are by default applied to the entire API. However, you can
implement an additional level of policy granularity, one in which access is controlled based on a
criteria. Policies with this granularity are called _resource-level policies_.

At the resource level of granularity, policies are applied to only those requests that match the
criteria. All policies, except the Cross-Origin Resource Sharing (CORS) policy, are resource-level.

For Omni Gateway running in Connected Mode, you configure resource-level policies in API Manager.

For information about configuring resource-level policies for Omni Gateway running in Local Mode,
refer to [Secure an API with an Automated Resource-Level Policy](https://docs.mulesoft.com/gateway/latest/local-secure-api-with-auto-policy).

<!-- document id=63a2d168bfcbcc8afc974091619ebecfd9307b9c7b7848974eb2d2d42e3cfc91 url=/mulesoft/current/en-us/gateway/1.12/policies-included-response-timeout.md -->

---
product: Omni Gateway
version: 1.12
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Response Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Response Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration that Flex Gateway waits for a response from an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Response Timeout policy enables you to set the maximum duration that Flex Gateway waits for a
response from an upstream service. The timeout time starts at the last request sent by Flex Gateway.

By default, all Flex Gateway API instances have a response timeout of 15 seconds. Apply the policy
to override the default timeout.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: response-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>15</p></div></div></td><td><div><div><p>Time in seconds Flex Gateway waits for the response.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: response-timeout-flex config: timeout: 3

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Response timeout</p></div></div></td><td><div><div><p>Time in seconds Flex Gateway waits for the response.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=f1ba789fe2fed15bdeff13603441771307e51d39aaace42ce31a9cb5c63c0812 url=/mulesoft/current/en-us/gateway/1.13/policies-included-response-timeout.md -->

---
product: Omni Gateway
version: 1.13
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Response Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Response Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration that Omni Gateway waits for a response from an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/response-timeout-release-notes">Response Timeout</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Response Timeout policy enables you to set the maximum duration that Omni Gateway waits for a
response from an upstream service. The timeout time starts at the last request sent by Omni Gateway.

By default, all Omni Gateway API instances have a response timeout of 15 seconds. Apply the policy
to override the default timeout.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: response-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>15</p></div></div></td><td><div><div><p>Time in seconds Omni Gateway waits for the response.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: response-timeout-flex config: timeout: 3

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Response timeout</p></div></div></td><td><div><div><p>Time in seconds Omni Gateway waits for the response.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=6089c55d1b4be7ddf6f1690647680f23c35ab914c470b51e64fafccfb4669979 url=/mulesoft/current/en-us/gateway/1.9/policies-included-response-timeout.md -->

---
product: Omni Gateway
version: 1.9
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Response Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Response Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration that Flex Gateway waits for a response from an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Response Timeout policy enables you to set the maximum duration that Flex Gateway waits for a
response from an upstream service. The timeout time starts at the last request sent by Flex Gateway.

By default, all Flex Gateway API instances have a response timeout of 15 seconds. Apply the policy
to override the default timeout.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: response-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>15</p></div></div></td><td><div><div><p>Time in seconds Flex Gateway waits for the response.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: response-timeout-flex config: timeout: 3

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Response timeout</p></div></div></td><td><div><div><p>Time in seconds Flex Gateway waits for the response.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=345e2142f835323c4e93556a68a1ae60d24e24eae42aa1ea01f547be7b144c7f url=/mulesoft/current/en-us/gateway/latest/policies-included-response-timeout.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Response Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Response Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration that Omni Gateway waits for a response from an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/response-timeout-release-notes">Response Timeout</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Response Timeout policy sets how long Omni Gateway waits for a response from an upstream service
before it returns a `504` error. The timer starts when Omni Gateway sends the request to the
upstream service.

Without this policy, an API instance uses the gateway-level Upstream Response Timeout. The
gateway-level default is 15 seconds.

This policy overrides every other Upstream Response Timeout configuration for the API instance you
apply it to, whether the policy value is higher or lower. To change the gateway-level timeout, see
[Configure Timeouts for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-timeout) or
[Configuring Timeouts in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-timeout).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: response-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>15</p></div></div></td><td><div><div><p>Number of seconds Omni Gateway waits for a response from the upstream service.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: response-timeout-flex config: timeout: 3

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Response timeout</p></div></div></td><td><div><div><p>Number of seconds Omni Gateway waits for a response from the upstream service.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=fe4c75541140a73f02d679551f514b13b474b3bda7b4cb3b9603cf5681347ede url=/mulesoft/current/en-us/gateway/1.12/policies-included-schema-validation.md -->

---
product: Omni Gateway
version: 1.12
keywords: oas3, schema validation, api gateway, flex gateway, gateway, policy
---

# Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Schema Validation Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming traffic against a supplied API schema</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - The request properties do not comply with the API specifications.</p></td></tr></tbody></table>

## Summary

> [!NOTE] The Schema Validation policy only supports REST APIs and currently only supports OpenAPI
> Specification 3.0 (OAS3) schema validations.

> [!NOTE] The Schema Validation policy supports a maximum of 64 bits for the `number` schema data
> type.

Applications processing REST API requests are susceptible to attacks such as header injection and
payload injection. Additional vulnerabilities can lead to the access of sensitive information. The
Schema Validation policy protects against such attacks and vulnerabilities by validating traffic
against a supplied API specification.

There are many ways to upload REST API specifications, but using Exchange is the easiest way. To
upload an API specification to Exchange, see
[Create an Exchange Asset](https://docs.mulesoft.com/exchange/to-create-an-asset).

Flex Gateway supports schemas defined in JSON or YAML, contained in a single file.

The Schema Validation policy validates request headers, queries, or path parameters.

Requests only include support for JSON format with content type `application/json`.

You configure the policy to perform one of the following actions:

- Block the request, and then return the 400 error status code.

- Allow the request, log the error, and then return the status code of the request.

You can validate content against:

- The presence of all required properties.

- The presence or absence of additional properties.

- The types of all properties.

  For example, if a schema specifies a property as an integer, the request must include an integer
  and not another type, such as a string.

- The format of the properties.

  For example, if the `pattern` keyword is specified, the policy validates the property as a regular
  expression.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: spec-validation-flex config: source: <string> // REQUIRED spec: <string> //
REQUIRED apiBasePath: <string> // OPTIONAL blockOperation: <boolean> // REQUIRED
strictParamsValidation: <boolean> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p>Determines if the schema is specified in this YAML resource, or if it’s specified in the API Context from Exchange (Connected Mode only). Supported values: <code>inline</code> or <code>context</code>. You must specify <code>inline</code> when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>spec</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>""</code></p></div></div></td><td><div><div><p>The actual inline specification. You must provide this when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>apiBasePath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>"/"</code></p></div></div></td><td><div><div><p>The base path of the API. You must provide this value when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>If <code>true</code>, the policy blocks an invalid spec validation. If <code>false</code>, the policy only logs an error.</p></div></div></td></tr><tr><td><div><div><p><code>strictParamsValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Determines whether to validate query parameters not defined in specification.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: spec-validation-flex
  config:
    source: "inline"
    apiBasePath: "/"
    blockOperation: true
    strictParamsValidation: false
    spec: |
      {
        "openapi": "3.0.2",
        ...
      }
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>Select to block an incoming request that does not conform to the API specification. Selecting not to block only logs the request. Choosing to block invalid requests returns a 400 status when the request is invalid.</p></div></div></td><td><div><div><p>Block enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Strict query parameters validation</p></div></div></td><td><div><div><p>Restricts API calls from query parameters not defined in the API Specification</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Advanced options</p></div></div></td><td><div></div></td><td><div></div></td><td><div></div></td></tr><tr><td><div><div><p>Policy version</p></div></div></td><td><div><div><p>Version of the applied policy</p></div></div></td><td><div><div><p>Latest</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Rule of application</p></div></div></td><td><div><div><p>Configures the runtimes the policy is applied to. Schema Validation is currently only available for Flex Gateway. Applying the policy to all runtimes only applies the policy to Flex Gateway APIs.</p></div></div></td><td><div><div><p>All runtimes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=e8c3c0faf5963e2613081035695ae79a3cf52f26a63942309ff67e0dee76df78 url=/mulesoft/current/en-us/gateway/1.13/policies-included-schema-validation.md -->

---
product: Omni Gateway
version: 1.13
keywords: oas3, schema validation, api gateway, flex gateway, gateway, policy
---

# Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Schema Validation Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming traffic against a supplied API schema</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/schema-validation-release-notes">Schema Validation Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - The request properties do not comply with the API specifications.</p></td></tr></tbody></table>

## Summary

> [!NOTE] The Schema Validation policy only supports REST APIs and currently only supports OpenAPI
> Specification 3.0 (OAS3) schema validations.

> [!NOTE] The Schema Validation policy supports a maximum of 64 bits for the `number` schema data
> type.

Applications processing REST API requests are susceptible to attacks such as header injection and
payload injection. Additional vulnerabilities can lead to the access of sensitive information. The
Schema Validation policy protects against such attacks and vulnerabilities by validating traffic
against a supplied API specification.

There are many ways to upload REST API specifications, but using Exchange is the easiest way. To
upload an API specification to Exchange, see
[Create an Exchange Asset](https://docs.mulesoft.com/exchange/to-create-an-asset).

Omni Gateway supports schemas defined in JSON or YAML, contained in a single file.

The Schema Validation policy validates request headers, queries, or path parameters.

Requests only include support for JSON format with content type `application/json`.

You configure the policy to perform one of the following actions:

- Block the request, and then return the 400 error status code.

- Allow the request, log the error, and then return the status code of the request.

You can validate content against:

- The presence of all required properties.

- The presence or absence of additional properties.

- The types of all properties.

  For example, if a schema specifies a property as an integer, the request must include an integer
  and not another type, such as a string.

- The format of the properties.

  For example, if the `pattern` keyword is specified, the policy validates the property as a regular
  expression.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: spec-validation-flex config: source: <string> // REQUIRED spec: <string> //
REQUIRED apiBasePath: <string> // OPTIONAL blockOperation: <boolean> // REQUIRED
strictParamsValidation: <boolean> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p>Determines if the schema is specified in this YAML resource, or if it’s specified in the API Context from Exchange (Connected Mode only). Supported values: <code>inline</code> or <code>context</code>. You must specify <code>inline</code> when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>spec</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>""</code></p></div></div></td><td><div><div><p>The actual inline specification. You must provide this when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>apiBasePath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>"/"</code></p></div></div></td><td><div><div><p>The base path of the API. You must provide this value when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>If <code>true</code>, the policy blocks an invalid spec validation. If <code>false</code>, the policy only logs an error.</p></div></div></td></tr><tr><td><div><div><p><code>strictParamsValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Determines whether to validate query parameters not defined in specification.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: spec-validation-flex
  config:
    source: "inline"
    apiBasePath: "/"
    blockOperation: true
    strictParamsValidation: false
    spec: |
      {
        "openapi": "3.0.2",
        ...
      }
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>Select to block an incoming request that does not conform to the API specification. Selecting not to block only logs the request. Choosing to block invalid requests returns a 400 status when the request is invalid.</p></div></div></td><td><div><div><p>Block enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Strict query parameters validation</p></div></div></td><td><div><div><p>Restricts API calls from query parameters not defined in the API Specification</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Advanced options</p></div></div></td><td><div></div></td><td><div></div></td><td><div></div></td></tr><tr><td><div><div><p>Policy version</p></div></div></td><td><div><div><p>Version of the applied policy</p></div></div></td><td><div><div><p>Latest</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Rule of application</p></div></div></td><td><div><div><p>Configures the runtimes the policy is applied to. Schema Validation is currently only available for Omni Gateway. Applying the policy to all runtimes only applies the policy to Omni Gateway APIs.</p></div></div></td><td><div><div><p>All runtimes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=2dd9209e8cd7ed1c9d51005e2bca73d08213132824e0c96ba2eeacd3274cb7b5 url=/mulesoft/current/en-us/gateway/1.9/policies-included-schema-validation.md -->

---
product: Omni Gateway
version: 1.9
keywords: oas3, schema validation, api gateway, flex gateway, gateway, policy
---

# Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Schema Validation Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming traffic against a supplied API schema</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - The request properties do not comply with the API specifications.</p></td></tr></tbody></table>

## Summary

> [!NOTE] The Schema Validation policy only supports REST APIs and currently only supports OpenAPI
> Specification 3.0 (OAS3) schema validations.

> [!NOTE] The Schema Validation policy supports a maximum of 64 bits for the `number` schema data
> type.

Applications processing REST API requests are susceptible to attacks such as header injection and
payload injection. Additional vulnerabilities can lead to the access of sensitive information. The
Schema Validation policy protects against such attacks and vulnerabilities by validating traffic
against a supplied API specification.

There are many ways to upload REST API specifications, but using Exchange is the easiest way. To
upload an API specification to Exchange, see
[Create an Exchange Asset](https://docs.mulesoft.com/exchange/to-create-an-asset).

Flex Gateway supports schemas defined in JSON or YAML, contained in a single file.

The Schema Validation policy validates request headers, queries, or path parameters.

Requests only include support for JSON format with content type `application/json`.

You configure the policy to perform one of the following actions:

- Block the request, and then return the 400 error status code.

- Allow the request, log the error, and then return the status code of the request.

You can validate content against:

- The presence of all required properties.

- The presence or absence of additional properties.

- The types of all properties.

  For example, if a schema specifies a property as an integer, the request must include an integer
  and not another type, such as a string.

- The format of the properties.

  For example, if the `pattern` keyword is specified, the policy validates the property as a regular
  expression.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: spec-validation-flex config: source: <string> // REQUIRED spec: <string> //
REQUIRED apiBasePath: <string> // OPTIONAL blockOperation: <boolean> // REQUIRED
strictParamsValidation: <boolean> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p>Determines if the schema is specified in this YAML resource, or if it’s specified in the API Context from Exchange (Connected Mode only). Supported values: <code>inline</code> or <code>context</code>. You must specify <code>inline</code> when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>spec</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>""</code></p></div></div></td><td><div><div><p>The actual inline specification. You must provide this when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>apiBasePath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>"/"</code></p></div></div></td><td><div><div><p>The base path of the API. You must provide this value when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>If <code>true</code>, the policy blocks an invalid spec validation. If <code>false</code>, the policy only logs an error.</p></div></div></td></tr><tr><td><div><div><p><code>strictParamsValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Determines whether to validate query parameters not defined in specification.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: spec-validation-flex
  config:
    source: "inline"
    apiBasePath: "/"
    blockOperation: true
    strictParamsValidation: false
    spec: |
      {
        "openapi": "3.0.2",
        ...
      }
```

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>Select to block an incoming request that does not conform to the API specification. Selecting not to block only logs the request. Choosing to block invalid requests returns a 400 status when the request is invalid.</p></div></div></td><td><div><div><p>Block enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Strict query parameters validation</p></div></div></td><td><div><div><p>Restricts API calls from query parameters not defined in the API Specification</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Advanced options</p></div></div></td><td><div></div></td><td><div></div></td><td><div></div></td></tr><tr><td><div><div><p>Policy version</p></div></div></td><td><div><div><p>Version of the applied policy</p></div></div></td><td><div><div><p>Latest</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Rule of application</p></div></div></td><td><div><div><p>Configures the runtimes the policy is applied to. Schema Validation is currently only available for Flex Gateway. Applying the policy to all runtimes only applies the policy to Flex Gateway APIs.</p></div></div></td><td><div><div><p>All runtimes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=8f5a368fb364cee8ba98d123ef48eaea3722c6841f302b565d607815c602230b url=/mulesoft/current/en-us/gateway/latest/policies-included-schema-validation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: oas3, schema validation, api gateway, flex gateway, gateway, policy
---

# Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Schema Validation Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming traffic against a supplied API schema</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.4.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/schema-validation-release-notes">Schema Validation Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - The request properties do not comply with the API specifications.</p></td></tr></tbody></table>

## Summary

> [!NOTE] The Schema Validation policy only supports REST APIs and currently only supports OpenAPI
> Specification 3.0 (OAS3) schema validations.

> [!NOTE] The Schema Validation policy supports a maximum of 64 bits for the `number` schema data
> type.

Applications processing REST API requests are susceptible to attacks such as header injection and
payload injection. Additional vulnerabilities can lead to the access of sensitive information. The
Schema Validation policy protects against such attacks and vulnerabilities by validating traffic
against a supplied API specification.

There are many ways to upload REST API specifications, but using Exchange is the easiest way. To
upload an API specification to Exchange, see
[Create an Exchange Asset](https://docs.mulesoft.com/exchange/to-create-an-asset).

Omni Gateway supports schemas defined in JSON or YAML, contained in a single file.

The Schema Validation policy validates request headers, queries, or path parameters.

Requests support the JSON format (content type `application/json`) and the `multipart/form-data`
format. Both content types are validated against their OAS schema definitions.

You configure the policy to perform one of the following actions:

- Block the request, and then return the 400 error status code.

- Allow the request, log the error, and then return the status code of the request.

You can validate content against:

- The presence of all required properties.

- The presence or absence of additional properties.

- The types of all properties.

  For example, if a schema specifies a property as an integer, the request must include an integer
  and not another type, such as a string.

- The format of the properties.

  For example, if the `pattern` keyword is specified, the policy validates the property as a regular
  expression.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: spec-validation-flex config: source: <string> // REQUIRED spec: <string> //
REQUIRED apiBasePath: <string> // OPTIONAL blockOperation: <boolean> // REQUIRED
strictParamsValidation: <boolean> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p>Determines if the schema is specified in this YAML resource, or if it’s specified in the API Context from Exchange (Connected Mode only). Supported values: <code>inline</code> or <code>context</code>. You must specify <code>inline</code> when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>spec</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>""</code></p></div></div></td><td><div><div><p>The actual inline specification. You must provide this when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>apiBasePath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>"/"</code></p></div></div></td><td><div><div><p>The base path of the API. You must provide this value when configuring the policy in Local Mode.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>If <code>true</code>, the policy blocks an invalid spec validation. If <code>false</code>, the policy only logs an error.</p></div></div></td></tr><tr><td><div><div><p><code>strictParamsValidation</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Determines whether to validate query parameters not defined in specification.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: spec-validation-flex
  config:
    source: "inline"
    apiBasePath: "/"
    blockOperation: true
    strictParamsValidation: false
    spec: |
      {
        "openapi": "3.0.2",
        ...
      }
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>Select to block an incoming request that does not conform to the API specification. Selecting not to block only logs the request. Choosing to block invalid requests returns a 400 status when the request is invalid.</p></div></div></td><td><div><div><p>Block enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Strict query parameters validation</p></div></div></td><td><div><div><p>Restricts API calls from query parameters not defined in the API Specification</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Advanced options</p></div></div></td><td><div></div></td><td><div></div></td><td><div></div></td></tr><tr><td><div><div><p>Policy version</p></div></div></td><td><div><div><p>Version of the applied policy</p></div></div></td><td><div><div><p>Latest</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Rule of application</p></div></div></td><td><div><div><p>Configures the runtimes the policy is applied to. Schema Validation is currently only available for Omni Gateway. Applying the policy to all runtimes only applies the policy to Omni Gateway APIs.</p></div></div></td><td><div><div><p>All runtimes</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=499f301a11459909531c31a3ecc1d5ef0bea73a7bbff079f26ce18e902d6a94b url=/mulesoft/current/en-us/gateway/1.12/flex-local-secure-api-with-auto-policy.md -->

---
product: Omni Gateway
version: 1.12
---

# Secure an API with an Automated Resource-Level Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Flex Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple resource-based YAML configuration for an API
with multiple upstream services, all secured with an automated resource-level authentication policy.

Refer to [Automated Policies](https://docs.mulesoft.com/gateway/1.12/policies-automated-overview) and
[Resource-Level Policies](https://docs.mulesoft.com/gateway/1.12/policies-resource-level-overview) for more information.

> [!NOTE] Automated policies can only be defined in resource-based configurations. The inline
> configuration model is not supported. For more information about the difference between
> resource-based and inline configuration models, see
> [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.12/flex-local-configuration-reference-guide).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-flex-gateway-on-linux">Publish an API Running Behind Flex Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in local mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

3.  Define an automated [basic authentication policy](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-simple) by adding
    the following `PolicyBinding` resource after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

6.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

7.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

8.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for more information.

- Flex Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

4.  Define an automated basic authentication policy by adding the following `PolicyBinding` resource
    after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

5.  Save the file. The gateway automatically refreshes the configuration.

6.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

7.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

8.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

9.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Flex Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory)

<!-- document id=0c1826ea1f5991a860c56aaf44aa2dc56faf0cbd3bb147d6e1de142616665f0c url=/mulesoft/current/en-us/gateway/1.13/local-secure-api-with-auto-policy.md -->

---
product: Omni Gateway
version: 1.13
---

# Secure an API with an Automated Resource-Level Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Omni Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple resource-based YAML configuration for an API
with multiple upstream services, all secured with an automated resource-level authentication policy.

Refer to [Automated Policies](https://docs.mulesoft.com/gateway/1.13/policies-automated-overview) and
[Resource-Level Policies](https://docs.mulesoft.com/gateway/1.13/policies-resource-level-overview) for more information.

> [!NOTE] Automated policies can only be defined in resource-based configurations. The inline
> configuration model is not supported. For more information about the difference between
> resource-based and inline configuration models, see
> [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.13/local-configuration-reference-guide).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-omni-gateway-on-linux">Publish an API Running Behind Omni Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in local mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more
  information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

3.  Define an automated [basic authentication policy](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-simple) by adding
    the following `PolicyBinding` resource after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

6.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

7.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

8.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more information.

- Omni Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

4.  Define an automated basic authentication policy by adding the following `PolicyBinding` resource
    after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

5.  Save the file. The gateway automatically refreshes the configuration.

6.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

7.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

8.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

9.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Omni Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

<!-- document id=e013499d08bd4f9112e0077167432802c910df7675dd51d29ffccb8742f042cb url=/mulesoft/current/en-us/gateway/1.9/flex-local-secure-api-with-auto-policy.md -->

---
product: Omni Gateway
version: 1.9
---

# Secure an API with an Automated Resource-Level Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Flex Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple resource-based YAML configuration for an API
with multiple upstream services, all secured with an automated resource-level authentication policy.

Refer to [Automated Policies](https://docs.mulesoft.com/gateway/1.9/policies-automated-overview) and
[Resource-Level Policies](https://docs.mulesoft.com/gateway/1.9/policies-resource-level-overview) for more information.

> [!NOTE] Automated policies can only be defined in resource-based configurations. The inline
> configuration model is not supported. For more information about the difference between
> resource-based and inline configuration models, see
> [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/1.9/flex-local-configuration-reference-guide).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-flex-gateway-on-linux">Publish an API Running Behind Flex Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in local mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

3.  Define an automated [basic authentication policy](https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-simple) by adding
    the following `PolicyBinding` resource after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

6.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

7.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

8.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for more information.

- Flex Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

4.  Define an automated basic authentication policy by adding the following `PolicyBinding` resource
    after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

5.  Save the file. The gateway automatically refreshes the configuration.

6.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

7.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

8.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

9.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Flex Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory)

<!-- document id=1c8e03d288c3191a87a2f5df647f97678db755089675aaefb9139e31edd78d14 url=/mulesoft/current/en-us/gateway/latest/local-secure-api-with-auto-policy.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Secure an API with an Automated Resource-Level Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Omni Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple resource-based YAML configuration for an API
with multiple upstream services, all secured with an automated resource-level authentication policy.

Refer to [Automated Policies](https://docs.mulesoft.com/gateway/latest/policies-automated-overview) and
[Resource-Level Policies](https://docs.mulesoft.com/gateway/latest/policies-resource-level-overview) for more information.

> [!NOTE] Automated policies can only be defined in resource-based configurations. The inline
> configuration model is not supported. For more information about the difference between
> resource-based and inline configuration models, see
> [Declarative Configuration Reference Guide](https://docs.mulesoft.com/gateway/latest/local-configuration-reference-guide).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-omni-gateway-on-linux">Publish an API Running Behind Omni Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in local mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more
  information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

3.  Define an automated [basic authentication policy](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple) by adding
    the following `PolicyBinding` resource after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

6.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

7.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

8.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more information.

- Omni Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following two `ApiInstance` resources into the file, substituting your values
    where indicated:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-api
    labels: secured-by-automated-policy: yes spec: address: http://0.0.0.0:8080 services: products:
    address: https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) -
    path: /products-featured(/.\*) config: destinationPath: /api
    ---

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: users-api labels:
    secured-by-automated-policy: yes spec: address: http://0.0.0.0:8081 services: users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*)

4.  Define an automated basic authentication policy by adding the following `PolicyBinding` resource
    after the `ApiInstance` resources:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin

    Applying an automated policy to multiple API instances requires that you specify the `Selector`
    `kind` in your policy binding. The example `PolicyBinding` resource includes a
    `spec.targetRef.kind` value of `Selector`, and a `spec.targetRef.selector.kind` value of
    `ApiInstance`.

    The example resource also applies a basic authentication policy to two API instances. It defines
    a `secured-by-automated-policy` label (the label name is customizable) in
    `spec.targetRef.selector.labels`. This label matches the label defined in the `ApiInstance`
    `metadata.labels` property, which associates the automated policy with that resource.

    Alternatively, automated policies can be applied to all API instances by omitting the labels.

5.  Save the file. The gateway automatically refreshes the configuration.

6.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/products-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/products(/.\*) methods:
    headerConditions:\[\] profile:0xc00004f750} => {Kind:Service Name:products-api-products
    Namespace:default} \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Policy
    default/envoy.filters.http.router \[agent\]\[info\] Gateway default/21cf4286e38f: Adding
    ApiInstance default/users-api http://0.0.0.0:8081 \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Policy default/security-protection \[agent\]\[info\] Gateway
    default/21cf4286e38f: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0061823f0} => {Kind:Service Name:users-api-users Namespace:default} \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Policy default/envoy.filters.http.router \[agent\]\[info\]
    Gateway default/21cf4286e38f: Adding Service default/products-api-products
    https://<your products URL>:<your port>/ \[agent\]\[debug\] generating service
    products-api-products.default.svc hostname: https://<your products URL> port: <your port>
    \[agent\]\[info\] Gateway default/21cf4286e38f: Adding Service default/users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    users-api-users.default.svc hostname: https://<your users URL> port: <your port>
    \[agent\]\[info\] Writing envoy bootstrap configuration to /tmp/envoy.json \[envoy\]\[info\]
    cds: add 2 cluster(s), remove 3 cluster(s) \[envoy\]\[info\] cds: added/updated 0 cluster(s),
    skipped 2 unmodified cluster(s)

7.  Test the APIs with a tool such as `curl`, specifying the given authentication credentials. The
    automated authentication policy secures both APIs.

8.  Apply resource-level granularity to the automated authentication policy by substituting the
    `PolicyBinding` resource with the following:

    \--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name:
    security-protection spec: targetRef: kind: Selector selector: kind: ApiInstance labels:
    secured-by-automated-policy: yes policyRef: name: http-basic-authentication-flex config:
    username: chris password: admin rules:
    - methods: GET

    In this example, the automated authentication policy is applied only to the `GET` method
    resource, as specified in `spec.rules`.

9.  Save the file. The gateway automatically refreshes the configuration.

Two APIs secured with the an automated resource-level authentication policy are now running behind
Omni Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

<!-- document id=770dccd33028185d56cd9ecf3fad21ed65dbc020c47ae8fd986626c9dab8f6e9 url=/mulesoft/current/en-us/gateway/1.12/flex-local-secure-api-with-basic-auth-policy.md -->

---
product: Omni Gateway
version: 1.12
---

# Secure an API with Basic Authentication and Rate Limiting

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Flex Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple YAML configuration for an API with multiple
upstream services, all secured with [basic authentication](https://docs.mulesoft.com/gateway/1.12/policies-included-basic-auth-simple) and
[rate limiting](https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-flex-gateway-on-linux">Publish an API Running Behind Flex Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in local mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) - path:
    /products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install) for more information.

- Flex Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /api/products(/.\*) - path:
    /api/products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Flex Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory)

<!-- document id=029e07df8370b9b6ac1fe38467b93837505e52e21bdfd059f205f05f6c9a30e5 url=/mulesoft/current/en-us/gateway/1.13/local-secure-api-with-basic-auth-policy.md -->

---
product: Omni Gateway
version: 1.13
---

# Secure an API with Basic Authentication and Rate Limiting

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Omni Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple YAML configuration for an API with multiple
upstream services, all secured with [basic authentication](https://docs.mulesoft.com/gateway/1.13/policies-included-basic-auth-simple) and
[rate limiting](https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-omni-gateway-on-linux">Publish an API Running Behind Omni Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in local mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more
  information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) - path:
    /products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install) for more information.

- Omni Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /api/products(/.\*) - path:
    /api/products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Omni Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

<!-- document id=bf720012c9d7b51da89e3af03b57b67cb76d5c7ac88a0f667c37aec6b023083b url=/mulesoft/current/en-us/gateway/1.9/flex-local-secure-api-with-basic-auth-policy.md -->

---
product: Omni Gateway
version: 1.9
---

# Secure an API with Basic Authentication and Rate Limiting

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Flex Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple YAML configuration for an API with multiple
upstream services, all secured with [basic authentication](https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-simple) and
[rate limiting](https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-flex-gateway-on-linux">Publish an API Running Behind Flex Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-flex-gateway-in-a-docker-container">Publish an API Running Behind Flex Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Flex Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed and running in local mode. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for
  more information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Flex Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) - path:
    /products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Flex Gateway.

## Publish an API Running Behind Flex Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Flex Gateway installed. See [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install) for more information.

- Flex Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Flex Gateway configuration
    files. This directory was specified when you started Flex Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /api/products(/.\*) - path:
    /api/products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Flex Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory)

<!-- document id=8051b3418aa3ed4e01802c000cda6f4026a286ebb572724b1a5cbf031b2e99a8 url=/mulesoft/current/en-us/gateway/latest/local-secure-api-with-basic-auth-policy.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Secure an API with Basic Authentication and Rate Limiting

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Publish an API running behind Omni Gateway in Local Mode, modifying YAML configuration data by the
following method:

- Linux and Docker: `.yaml` files

The following procedures demonstrate applying a simple YAML configuration for an API with multiple
upstream services, all secured with [basic authentication](https://docs.mulesoft.com/gateway/latest/policies-included-basic-auth-simple) and
[rate limiting](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting).

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-on-linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></td><td><p><span><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></td></tr><tr><td><p><a href="#publish-an-api-running-behind-omni-gateway-on-linux">Publish an API Running Behind Omni Gateway on Linux</a></p></td><td><p><a href="#publish-an-api-running-behind-omni-gateway-in-a-docker-container">Publish an API Running Behind Omni Gateway in a Docker Container</a></p></td></tr></tbody></table>

## Publish an API Running Behind Omni Gateway on Linux

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed and running in local mode. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more
  information about installing and running the gateway.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file in the Omni Gateway configuration directory
        `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple
        configuration files.

2.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /products(/.\*) - path:
    /products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

3.  Save the file. The gateway automatically refreshes the configuration.

4.  View the logs by executing the following command:

    journalctl -u flex-gateway-\*

    The response looks something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Omni Gateway.

## Publish an API Running Behind Omni Gateway in a Docker Container

### Before You Begin

Before getting started, ensure that you have:

- Omni Gateway installed. See [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install) for more information.

- Omni Gateway registered and running in Local Mode. See
  [Register and Run in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run) for more information.

- Your upstream service URLs. The following example refers to fictional `products-api` and
  `users-api` services, but you can specify your own API name in `metadata.name` and your service
  details in `spec.services`.

### Publish an API

1.  Open a terminal and navigate to the directory that will contain your Omni Gateway configuration
    files. This directory was specified when you started Omni Gateway.

2.  Create a configuration file with a `.yaml` file extension:

    1.  Give the file a custom name.

    2.  Save the file.

3.  Copy and paste the following YAML snippet into the file, substituting your values where
    indicated:

    apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: products-users-api
    spec: address: http://0.0.0.0:8080 services: products: address:
    https://<your products URL>:<your port>/ routes: - rules: - path: /api/products(/.\*) - path:
    /api/products-featured(/.\*) config: destinationPath: /api users: address:
    https://<your users URL>:<your port>/ routes: - rules: - path: /api/users(/.\*) policies: -
    policyRef: name: http-basic-authentication-flex config: username: chris password: admin -
    policyRef: name: rate-limiting-flex config: exposeHeaders: true rateLimits: - maximumRequests: 3
    timePeriodInMilliseconds: 6000 keySelector: "#\[attributes.queryParams\['identifier'\]\]"

4.  Save the file. The gateway automatically refreshes the configuration.

5.  View the Docker container logs, which look something like this:

    \[agent\]\[info\] Generating config \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding
    ApiInstance default/products-users-api http://0.0.0.0:8080 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy
    default/products-users-api-users-http-basic-authentication-flex-1 \[agent\]\[info\] Gateway
    default/4191c977e1ce: Adding Policy default/products-users-api-users-rate-limiting-flex-2
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Route: &{host: path:/api/products(/.\*)
    methods: headerConditions:\[\] profile:0xc0030529f0} => {Kind:Service
    Name:products-users-api-products Namespace:default} \[agent\]\[info\] Gateway
    default/18b4e890fe7d: Adding Route: &{host: path:/api/users(/.\*) methods: headerConditions:\[\]
    profile:0xc0030529f0} => {Kind:Service Name:products-users-api-users Namespace:default}
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Policy default/envoy.filters.http.router
    \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service default/monitoring\_metrics
    http://0.0.0.0:9881 \[agent\]\[debug\] generating service monitoring\_metrics.default.svc
    hostname: 0.0.0.0 port: 9881 \[agent\]\[info\] Gateway default/18b4e890fe7d: Adding Service
    default/products-users-api-products https://<your products URL>:<your port>/ \[agent\]\[info\]
    Gateway default/18b4e890fe7d: Adding Service default/products-users-api-users
    https://<your users URL>:<your port>/ \[agent\]\[debug\] generating service
    products-users-api-products.default.svc hostname: <your products URL> port: <your port>
    \[agent\]\[debug\] generating service products-users-api-users.default.svc hostname:
    <your users URL> port: <your port> \[agent\]\[info\] Writing envoy bootstrap configuration to
    /tmp/envoy.json \[envoy\]\[info\] cds: add 2 cluster(s), remove 2 cluster(s) \[envoy\]\[info\]
    cds: added/updated 1 cluster(s), skipped 1 unmodified cluster(s)

An API secured with basic authentication and rate limiting is now running behind Omni Gateway.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

<!-- document id=61aa46ce6443ec8d86eb1fe66e66756b468ddab458bbe7aa2303b30a0cf8359e url=/mulesoft/current/en-us/gateway/1.12/flex-agent-secure.md -->

---
product: Omni Gateway
version: 1.12
---

# Securing Agent Interactions with Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports both the Model Context Protocol (MCP) and the Agent2Agent (A2A) Protocol,
enabling you to protect your agents, brokers, LLM, and MCP servers. Flex Gateway provides
centralized oversight, agent visibility, logging, and valuable insights, ensuring effective
governance and security for your agent-based architecture. Flex Gateway secures agent interactions
by enforcing policies across agent connections and by monitoring agent activities for enhanced
visibility.

## Flex Gateway A2A Support

A2A is an open standard that defines how agents interact with each other, enabling interoperability
for agents built by different teams, using different technologies and hosted by different
organizations.

Flex Gateway protects agent A2A interactions by requiring appropriate authentication and
authorization for agent requests, rewriting Agent Card URLs, logging or blocking sensitive
information in messages, and logging Server-Sent Events (SSE) content for compliance audits. You can
enhance agent requests by modifying incoming prompts with additional context to improve server-agent
execution.

## Flex Gateway MCP Support

MCP is an open protocol that defines how agents interact with tools or external context, enabling
agents to connect to the data and tools they need.

Flex Gateway secures MCP connections by restricting MCP endpoint access to authorized agents only
and by simplifying governance through centralized visibility and control over all interactions.

## Securing Agent Interactions with Policies

Flex Gateway includes A2A and MCP specific policies that provide enhanced security and control over
agent interactions. Flex Gateway A2A policies enable you to protect agent endpoints by rewriting
Agent Card URLs, logging or blocking sensitive information in messages, modifying prompt behavior,
and logging Server-Sent Events (SSE) content for compliance audits. Flex Gateway MCP policies enable
you to use attribute-based access control to manage access to MCP servers.

Flex Gateway MCP and A2A server instances also support Flex Gateway’s other policies. For example,
use policies such as [Rate Limiting Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting) or
[Spike Control Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-spike-control) to manage the number of requests to MCP and
A2A servers or use the [Message Logging Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-message-logging) to monitor agent
interactions.

See [Flex Gateway Agent Policies](https://docs.mulesoft.com/gateway/1.12/flex-agent-policies) to learn about included A2A and MCP policies.

## See Also

- [Introducing Governance for Agent Interactions With Support for A2A & MCP](https://blogs.mulesoft.com/news/mulesoft-governance-for-agent-interactions/)

- [A2A Protocol spec](https://a2a-protocol.org/latest/topics/what-is-a2a/)

- [MCP Protocol spec](https://modelcontextprotocol.io/introduction)

- [Streaming & Asynchronous Operations in A2A](https://a2a-protocol.org/latest/topics/streaming-and-async/)

<!-- document id=3690e7ba5c08e1d71e96afb4488221b7c36dd1f90b4931645f56fd2e6e3d0031 url=/mulesoft/current/en-us/gateway/1.9/flex-agent-secure.md -->

---
product: Omni Gateway
version: 1.9
---

# Securing Agent Interactions with Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway supports both the Model Context Protocol (MCP) and the Agent2Agent (A2A) Protocol,
enabling you to protect your agents and systems. Flex Gateway provides centralized oversight, agent
visibility, logging, and valuable insights, ensuring effective governance and security for your
agent-based architecture. Flex Gateway secures agent interactions by enforcing policies across agent
connections and by monitoring agent activities for enhanced visibility.

## Flex Gateway A2A Support

A2A is an open standard that defines how agents interact with each other, enabling interoperability
for agents built by different teams, using different technologies and hosted by different
organizations.

Flex Gateway protects agent A2A interactions by requiring appropriate authentication and
authorization for agent requests, rewriting Agent Card URLs, logging or blocking sensitive
information in messages, and logging Server-Sent Events (SSE) content for compliance audits. You can
enhance agent requests by modifying incoming prompts with additional context to improve server-agent
execution.

## Flex Gateway MCP Support

MCP is an open protocol that defines how agents interact with tools or external context, enabling
agents to connect to the data and tools they need.

Flex Gateway secures MCP connections by restricting MCP endpoint access to authorized agents only
and by simplifying governance through centralized visibility and control over all interactions.

## Securing Agent Interactions with Policies

Flex Gateway includes A2A and MCP specific policies that provide enhanced security and control over
agent interactions. Flex Gateway A2A policies enable you to protect agent endpoints by rewriting
Agent Card URLs, logging or blocking sensitive information in messages, modifying prompt behavior,
and logging Server-Sent Events (SSE) content for compliance audits. Flex Gateway MCP policies enable
you to use attribute-based access control to manage access to MCP servers.

Flex Gateway MCP and A2A server instances also support Flex Gateway’s other policies. For example,
use policies such as [Rate Limiting Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting) or
[Spike Control Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-spike-control) to manage the number of requests to MCP and
A2A servers or use the [Message Logging Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-message-logging) to monitor agent
interactions.

See [Flex Gateway Agent Policies](https://docs.mulesoft.com/gateway/1.9/flex-agent-policies) to learn about included A2A and MCP policies.

## See Also

- [Introducing Governance for Agent Interactions With Support for A2A & MCP](https://blogs.mulesoft.com/news/mulesoft-governance-for-agent-interactions/)

- [What is A2A?](https://a2a-protocol.org/latest/topics/what-is-a2a/)

- [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/)

- [MCP Protocol Specification](https://modelcontextprotocol.io/docs/getting-started/intro)

- [Streaming & Asynchronous Operations in A2A](https://a2a-protocol.org/latest/topics/streaming-and-async/)

<!-- document id=31029802bfcfea0869fe547c0b2d36bb9011758dc9f7cbeb0dbed99e760b59b5 url=/mulesoft/current/en-us/gateway/1.13/agent-secure.md -->

---
product: Omni Gateway
version: 1.13
---

# Securing Agent Interactions with Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports both the Model Context Protocol (MCP) and the Agent2Agent (A2A) Protocol,
enabling you to protect your agents, brokers, LLM, and MCP servers. Omni Gateway provides
centralized oversight, agent visibility, logging, and valuable insights, ensuring effective
governance and security for your agent-based architecture. Omni Gateway secures agent interactions
by enforcing policies across agent connections and by monitoring agent activities for enhanced
visibility.

## Omni Gateway A2A Support

A2A is an open standard that defines how agents interact with each other, enabling interoperability
for agents built by different teams, using different technologies and hosted by different
organizations.

Omni Gateway protects agent A2A interactions by requiring appropriate authentication and
authorization for agent requests, rewriting Agent Card URLs, logging or blocking sensitive
information in messages, and logging Server-Sent Events (SSE) content for compliance audits. You can
enhance agent requests by modifying incoming prompts with additional context to improve server-agent
execution.

## Omni Gateway MCP Support

MCP is an open protocol that defines how agents interact with tools or external context, enabling
agents to connect to the data and tools they need.

Omni Gateway secures MCP connections by restricting MCP endpoint access to authorized agents only
and by simplifying governance through centralized visibility and control over all interactions.

## Securing Agent Interactions with Policies

Omni Gateway includes A2A and MCP specific policies that provide enhanced security and control over
agent interactions. Omni Gateway A2A policies enable you to protect agent endpoints by rewriting
Agent Card URLs, logging or blocking sensitive information in messages, modifying prompt behavior,
and logging Server-Sent Events (SSE) content for compliance audits. Omni Gateway MCP policies enable
you to use attribute-based access control to manage access to MCP servers.

Omni Gateway MCP and A2A server instances also support Omni Gateway’s other policies. For example,
use policies such as [Rate Limiting Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting) or
[Spike Control Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-spike-control) to manage the number of requests to MCP and
A2A servers or use the [Message Logging Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-message-logging) to monitor agent
interactions.

See [Omni Gateway Agent Policies](https://docs.mulesoft.com/gateway/1.13/agent-policies) to learn about included A2A and MCP policies.

## See Also

- [Introducing Governance for Agent Interactions With Support for A2A & MCP](https://blogs.mulesoft.com/news/mulesoft-governance-for-agent-interactions/)

- [A2A Protocol spec](https://a2a-protocol.org/latest/topics/what-is-a2a/)

- [MCP Protocol spec](https://modelcontextprotocol.io/introduction)

- [Streaming & Asynchronous Operations in A2A](https://a2a-protocol.org/latest/topics/streaming-and-async/)

<!-- document id=21d493a87aa8318270f73f640475fccd48d1c10f7ea0d8ed09efa460f5a35746 url=/mulesoft/current/en-us/gateway/latest/agent-secure.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Securing Agent Interactions with Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway supports both the Model Context Protocol (MCP) and the Agent2Agent (A2A) Protocol,
enabling you to protect your agents, brokers, LLM, and MCP servers. Omni Gateway provides
centralized oversight, agent visibility, logging, and valuable insights, ensuring effective
governance and security for your agent-based architecture. Omni Gateway secures agent interactions
by enforcing policies across agent connections and by monitoring agent activities for enhanced
visibility.

## Omni Gateway A2A Support

A2A is an open standard that defines how agents interact with each other, enabling interoperability
for agents built by different teams, using different technologies and hosted by different
organizations.

Omni Gateway protects agent A2A interactions by requiring appropriate authentication and
authorization for agent requests, rewriting Agent Card URLs, logging or blocking sensitive
information in messages, and logging Server-Sent Events (SSE) content for compliance audits. You can
enhance agent requests by modifying incoming prompts with additional context to improve server-agent
execution.

## Omni Gateway MCP Support

MCP is an open protocol that defines how agents interact with tools or external context, enabling
agents to connect to the data and tools they need.

Omni Gateway secures MCP connections by restricting MCP endpoint access to authorized agents only
and by simplifying governance through centralized visibility and control over all interactions.

## Securing Agent Interactions with Policies

Omni Gateway includes A2A and MCP specific policies that provide enhanced security and control over
agent interactions. Omni Gateway A2A policies enable you to protect agent endpoints by rewriting
Agent Card URLs, logging or blocking sensitive information in messages, modifying prompt behavior,
and logging Server-Sent Events (SSE) content for compliance audits. Omni Gateway MCP policies enable
you to use attribute-based access control to manage access to MCP servers.

Omni Gateway MCP and A2A server instances also support Omni Gateway’s other policies. For example,
use policies such as [Rate Limiting Policy](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting) or
[Spike Control Policy](https://docs.mulesoft.com/gateway/latest/policies-included-spike-control) to manage the number of requests to MCP and
A2A servers or use the [Message Logging Policy](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging) to monitor agent
interactions.

See [Omni Gateway Agent Policies](https://docs.mulesoft.com/gateway/latest/agent-policies) to learn about included A2A and MCP policies.

## See Also

- [Introducing Governance for Agent Interactions With Support for A2A & MCP](https://blogs.mulesoft.com/news/mulesoft-governance-for-agent-interactions/)

- [A2A Protocol spec](https://a2a-protocol.org/latest/topics/what-is-a2a/)

- [MCP Protocol spec](https://modelcontextprotocol.io/introduction)

- [Streaming & Asynchronous Operations in A2A](https://a2a-protocol.org/latest/topics/streaming-and-async/)

<!-- document id=a46ffbbea5bf05241ac6ffe9ea471ca49a6caf92a22f5674ce34e4e8724a0e65 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-secure-apis.md -->

---
product: Omni Gateway
version: 1.9
---

# Securing Flex Gateway APIs with Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Flex Gateway processes requests, enabling you to secure and govern your
Flex Gateway APIs.

MuleSoft provides policies that you can apply to your APIs via Anypoint Platform or declarative
configuration files. The provided policies include rate limiting, caching, authentication,
authorization, threat protection, monitoring, and logging. For more information about
MuleSoft-provided policies, see the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.9/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements and apply them to APIs. For information about creating custom
policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Automated policies enable your API instance to comply with common security and logging requirements
by automatically applying the same set of policies to all APIs running in Flex Gateway. See
[Automated Policies](https://docs.mulesoft.com/gateway/1.9/policies-automated-overview) for more information.

To apply a policy for Managed Flex Gateway or Connected Mode, see
[Applying Policies for Managed Flex Gateways and Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-secure-conn).

To apply a policy in Local Mode, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-gateway-secure-local).

For information about policy reordering, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.9/policies-reorder).

For information about DataWeave support, see
[DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.9/policies-flex-dataweave-support).

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

- [Getting Started with Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started-overview)

<!-- document id=bcc18039275d43684be43696c0d6dd0d6021a55b22ec97a756210804a969786d url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-secure-apis.md -->

---
product: Omni Gateway
version: 1.12
---

# Securing Flex Gateway Instances with Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Flex Gateway processes requests, enabling you to secure and govern your
Flex Gateway API, agent, and tool instances.

MuleSoft provides policies that you can apply to your instances via Anypoint Platform or declarative
configuration files. The provided policies include rate limiting, caching, authentication,
authorization, threat protection, monitoring, and logging. For more information about
MuleSoft-provided policies, see the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.12/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements. For information about creating custom policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Automated policies enable your instances to comply with common security and logging requirements by
automatically applying the same set of policies to all instances running in Flex Gateway. See
[Automated Policies](https://docs.mulesoft.com/gateway/1.12/policies-automated-overview) for more information.

To apply a policy for Managed Flex Gateway or Connected Mode, see
[Applying Policies for Managed Flex Gateways and Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-secure-conn).

To apply a policy in Local Mode, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-gateway-secure-local).

For information about policy reordering, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder).

For information about DataWeave support, see
[DataWeave Support in Flex Gateway Policies](https://docs.mulesoft.com/gateway/1.12/policies-flex-dataweave-support).

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

- [Getting Started with Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started-overview)

<!-- document id=266d3336ad218d97e7618f76ded66dbbbe4c42cdc298f675eb8473e33984501e url=/mulesoft/current/en-us/gateway/1.13/gateway-secure-apis.md -->

---
product: Omni Gateway
version: 1.13
---

# Securing Omni Gateway Instances with Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Omni Gateway processes requests, enabling you to secure and govern your
Omni Gateway API, agent, and tool instances.

MuleSoft provides policies that you can apply to your instances via Anypoint Platform or declarative
configuration files. The provided policies include rate limiting, caching, authentication,
authorization, threat protection, monitoring, logging. For more information about MuleSoft-provided
policies, see the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements. For information about creating custom policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Automated policies enable your instances to comply with common security and logging requirements by
automatically applying the same set of policies to all instances running in Omni Gateway. See
[Automated Policies](https://docs.mulesoft.com/gateway/1.13/policies-automated-overview) for more information.

To apply a policy for Managed Omni Gateway or Connected Mode, see
[Applying Policies for Managed Omni Gateways and Connected Mode](https://docs.mulesoft.com/gateway/1.13/gateway-secure-conn).

To apply a policy in Local Mode, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/1.13/gateway-secure-local).

For information about policy reordering, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder).

For information about DataWeave support, see
[DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support).

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

- [Getting Started with Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started-overview)

<!-- document id=b65b713de0bdd364c54ab952195913b85ea501167b7e1dc453e7bc3fa6dbd3a3 url=/mulesoft/current/en-us/gateway/latest/gateway-secure-apis.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Securing Omni Gateway Instances with Policies

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Policies enforce rules when Omni Gateway processes requests, enabling you to secure and govern your
Omni Gateway API, agent, and tool instances.

MuleSoft provides policies that you can apply to your instances via Anypoint Platform or declarative
configuration files. The provided policies include rate limiting, caching, authentication,
authorization, threat protection, monitoring, logging. For more information about MuleSoft-provided
policies, see the [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory) and
[Outbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-outbound-directory).

To extend existing functionality or define new functionality, create custom policies based on your
specific business requirements. For information about creating custom policies, see
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

Automated policies enable your instances to comply with common security and logging requirements by
automatically applying the same set of policies to all instances running in Omni Gateway. See
[Automated Policies](https://docs.mulesoft.com/gateway/latest/policies-automated-overview) for more information.

To apply a policy for Managed Omni Gateway or Connected Mode, see
[Applying Policies for Managed Omni Gateways and Connected Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-conn).

To apply a policy in Local Mode, see [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-local).

For information about policy reordering, see [Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder).

For information about DataWeave support, see
[DataWeave Support in Omni Gateway Policies](https://docs.mulesoft.com/gateway/latest/policies-dataweave-support).

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

- [Getting Started with Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started-overview)

<!-- document id=f453befc14b91c350e605fb595fcc884233978602b8cfd8f3e6a9e1beae987a7 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-multi-region.md -->

---
product: Omni Gateway
version: 1.12
---

# Self Managed Flex Gateway High Availability, Disaster Recovery, and Multi-Region Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Install Flex Gateway in multiple regions to reduce latency and ensure live failover. You can
configure most implementations with either multiple Flex Gateways or multiple Flex Replicas.
Depending on which you choose, there are different considerations for Redis Shared-Storage,
policies, and logging. To learn more about Flex Replicas, see [Flex Replicas](https://docs.mulesoft.com/gateway/1.12/#replicas).

All the following diagrams show Flex Gateway running in Connected Mode. For Flex Gateway running in
Local Mode, the only difference is that Anypoint Platform isn’t present in the deployment model.
This doesn’t affect how information flows between Flex Gateway and the upstream and downstream
services.

The implementation diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

## Implementation 1: High Availability with the Same APIs in Two Separate Regions

Implementation 1 provides high availability for non-region-specific traffic. The DNS service is
configured for active-active failover, meaning each region services traffic at all times.

### Implementation 1A: Cross-Regional Flex Gateway

In this implementation:

- A single Flex Gateway has Flex Replicas distributed across multiple regions.

- Flex Gateway is registered once in Anypoint Platform and deployed across multiple regions and
  availability zones.

- Logs and metrics for each Flex Gateway are consolidated in Anypoint Platform.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- APIs deployed to the Gateway are available in all regions and availability zones.

- API configurations, including upstream services and policies are the same for all regions.
  Upstream services must be region-agnostic, meaning either the DNS is local or it lacks any
  reference to the region.

- The Redis cluster must be replicated across regions or Redis shared storage can’t be used. Redis
  replication is required when traffic isn’t region-specific.

- The only cross-regional traffic is Redis synchronization.

In the following diagram, Flex Replicas in different regions and availability zones have distinct
Kubernetes deployments:

![A detailed view of implementation 1A, which contains the necessary services to support high availability in for Flex Replicas deployed in different regions](/mulesoft/current/en-us/gateway/1.12/_images/high-availability-1a.png)

### Implementation 1B: Region-Specific Flex Gateway

In this implementation:

- Each region has a distinct Flex Gateway with all resources as independent entities.

- A separate Flex Gateway is registered for each region.

- Each region-specific API instance has distinct metrics, alerts, and logs in Anypoint Platform.

- Policies are region specific even if the configuration is similar across regions.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- API deployments are specific to each Flex Gateway. For each API a region supports, you must deploy
  an API instance to the region’s Flex Gateway.

- API Groups can share contracts (access requests) across regions. An API Group might not be
  required for your configuration.

- Redis shared storage does not require synchronization.

- There is no cross-regional traffic.

In the following diagram, all APIs are duplicated and don’t require identical configurations:

![A detailed view of implementation 1B, which contains the necessary services to support high availability for region-specific Flex Gateways](/mulesoft/current/en-us/gateway/1.12/_images/high-availability-1b.png)

## Implementation 2: Disaster Recovery for APIs

This implementation is similar to
[Implementation 1A: Cross-Regional Flex Gateway](#implementation-1a). However, the DNS service is
active-passive, so the standby region only receives traffic if the primary region becomes unhealthy.
This implementation is less complex to configure than implementation 1A.

Redis synchronization is not required if a cache loss during failover is acceptable.

In the following diagram, Flex Replicas in different availability zones have distinct Kubernetes
deployments. Region B provides high availability but receives traffic only if region A is unhealthy:

![A detailed view of implementation 2, which contains the necessary services to enable disaster recovery for APIs on Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/high-availability-2.png)

## Implementation 3: Direct Traffic to the Closest Region

In both [Implementation 3A: Direct Traffic to APIs With the Same Policies](#implementation-3a) and
[Implementation 3B: Direct Traffic to APIs With the Different Policies](#implementation-3b), Flex
Gateway directs traffic to the most convenient region to reduce latency. Choose which implementation
according to your policy requirements.

### Implementation 3A: Direct Traffic to APIs With the Same Policies

This implementation is similar to
[Implementation 1A: Cross-Regional Flex Gateway](#implementation-1a) and has the same
considerations. However, Redis replication is not required because requests are sent to specific
regions. Configure high availability or disaster recovery zones in each region to ensure API
availability:

![A detailed view of implementation 3A, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/1.12/_images/high-availability-3a.png)

### Implementation 3B: Direct Traffic to APIs With the Different Policies

This implementation is similar to
[Implementation 1B: Region-Specific Flex Gateway](#implementation-1b) and has the same
considerations. Deploy region-specific gateways and apply the necessary policies to the different
APIs. Configure high availability or disaster recovery zones in each region to ensure API
availability:

![A detailed view of implementation 3B, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/1.12/_images/high-availability-3b.png)

> [!NOTE] To apply SLA rate limiting across all regions, the rate limits must be the same for all
> regions. Use API groups to consolidate the contracts.

<!-- document id=29be4166c179d6a9a2518fc846586c09a12cb97959bfe689a6792ea3107fe2d0 url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-multi-region.md -->

---
product: Omni Gateway
version: 1.13
---

# Self Managed Omni Gateway High Availability, Disaster Recovery, and Multi-Region Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Install Omni Gateway in multiple regions to reduce latency and ensure live failover. You can
configure most implementations with either multiple Omni Gateways or multiple Omni Replicas.
Depending on which you choose, there are different considerations for Redis shared storage,
policies, and logging. To learn more about Omni Replicas, see [Omni Replicas](https://docs.mulesoft.com/gateway/1.13/#replicas).

> [!NOTE] The implementations below discuss Redis shared storage considerations. You can also use
> distributed shared storage, which doesn’t require cross-region synchronization. However, data is
> lost when all replicas go down (scaled to zero replicas).

All the following diagrams show Omni Gateway running in Connected Mode. For Omni Gateway running in
Local Mode, the only difference is that Anypoint Platform isn’t present in the deployment model.
This doesn’t affect how information flows between Omni Gateway and the upstream and downstream
services.

The implementation diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

## Implementation 1: High Availability with the Same APIs in Two Separate Regions

Implementation 1 provides high availability for non-region-specific traffic. The DNS service is
configured for active-active failover, meaning each region services traffic at all times.

### Implementation 1A: Cross-Regional Omni Gateway

In this implementation:

- A single Omni Gateway has Omni Replicas distributed across multiple regions.

- Omni Gateway is registered once in Anypoint Platform and deployed across multiple regions and
  availability zones.

- Logs and metrics for each Omni Gateway are consolidated in Anypoint Platform.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- APIs deployed to the Gateway are available in all regions and availability zones.

- API configurations, including upstream services and policies are the same for all regions.
  Upstream services must be region-agnostic, meaning either the DNS is local or it lacks any
  reference to the region.

- If using Redis shared storage: The Redis cluster must be replicated across regions or Redis shared
  storage can’t be used. Redis replication is required when traffic isn’t region-specific.

- If using Redis shared storage: The only cross-regional traffic is Redis synchronization.

- If using distributed shared storage: No cross-region synchronization is needed, but cached data is
  lost after gateway restarts.

In the following diagram, Omni Replicas in different regions and availability zones have distinct
Kubernetes deployments:

![A detailed view of implementation 1A, which contains the necessary services to support high availability in for Omni Replicas deployed in different regions](/mulesoft/current/en-us/gateway/1.13/_images/high-availability-1a.png)

### Implementation 1B: Region-Specific Omni Gateway

In this implementation:

- Each region has a distinct Omni Gateway with all resources as independent entities.

- A separate Omni Gateway is registered for each region.

- Each region-specific API instance has distinct metrics, alerts, and logs in Anypoint Platform.

- Policies are region specific even if the configuration is similar across regions.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- API deployments are specific to each Omni Gateway. For each API a region supports, you must deploy
  an API instance to the region’s Omni Gateway.

- API Groups can share contracts (access requests) across regions. An API Group might not be
  required for your configuration.

- If using Redis shared storage: Redis does not require synchronization.

- If using distributed shared storage: No cross-region synchronization is needed.

- There is no cross-regional traffic.

In the following diagram, all APIs are duplicated and don’t require identical configurations:

![A detailed view of implementation 1B, which contains the necessary services to support high availability for region-specific Omni Gateways](/mulesoft/current/en-us/gateway/1.13/_images/high-availability-1b.png)

## Implementation 2: Disaster Recovery for APIs

This implementation is similar to
[Implementation 1A: Cross-Regional Omni Gateway](#implementation-1a). However, the DNS service is
active-passive, so the standby region only receives traffic if the primary region becomes unhealthy.
This implementation is less complex to configure than implementation 1A.

If using Redis shared storage: Redis synchronization is not required if a cache loss during failover
is acceptable. If using distributed shared storage: No synchronization is needed, but cached data is
lost after gateway restarts.

In the following diagram, Omni Replicas in different availability zones have distinct Kubernetes
deployments. Region B provides high availability but receives traffic only if region A is unhealthy:

![A detailed view of implementation 2, which contains the necessary services to enable disaster recovery for APIs on Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/high-availability-2.png)

## Implementation 3: Direct Traffic to the Closest Region

In both [Implementation 3A: Direct Traffic to APIs With the Same Policies](#implementation-3a) and
[Implementation 3B: Direct Traffic to APIs With the Different Policies](#implementation-3b), Omni
Gateway directs traffic to the most convenient region to reduce latency. Choose which implementation
according to your policy requirements.

### Implementation 3A: Direct Traffic to APIs With the Same Policies

This implementation is similar to
[Implementation 1A: Cross-Regional Omni Gateway](#implementation-1a) and has the same
considerations. However, if using Redis shared storage, Redis replication is not required because
requests are sent to specific regions. Configure high availability or disaster recovery zones in
each region to ensure API availability:

![A detailed view of implementation 3A, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/1.13/_images/high-availability-3a.png)

### Implementation 3B: Direct Traffic to APIs With the Different Policies

This implementation is similar to
[Implementation 1B: Region-Specific Omni Gateway](#implementation-1b) and has the same
considerations. Deploy region-specific gateways and apply the necessary policies to the different
APIs. Configure high availability or disaster recovery zones in each region to ensure API
availability:

![A detailed view of implementation 3B, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/1.13/_images/high-availability-3b.png)

> [!NOTE] To apply SLA rate limiting across all regions, the rate limits must be the same for all
> regions. Use API groups to consolidate the contracts.

<!-- document id=f072368625714b1797c325d2fe1d7603c9897bcc3b12e04f75410b6dc0bb6676 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-multi-region.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Self Managed Omni Gateway High Availability, Disaster Recovery, and Multi-Region Deployments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Install Omni Gateway in multiple regions to reduce latency and ensure live failover. You can
configure most implementations with either multiple Omni Gateways or multiple Omni Replicas.
Depending on which you choose, there are different considerations for Redis shared storage,
policies, and logging. To learn more about Omni Replicas, see [Omni Replicas](https://docs.mulesoft.com/gateway/latest/#replicas).

> [!NOTE] The implementations below discuss Redis shared storage considerations. You can also use
> distributed shared storage, which doesn’t require cross-region synchronization. However, data is
> lost when all replicas go down (scaled to zero replicas).

All the following diagrams show Omni Gateway running in Connected Mode. For Omni Gateway running in
Local Mode, the only difference is that Anypoint Platform isn’t present in the deployment model.
This doesn’t affect how information flows between Omni Gateway and the upstream and downstream
services.

The implementation diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

## Implementation 1: High Availability with the Same APIs in Two Separate Regions

Implementation 1 provides high availability for non-region-specific traffic. The DNS service is
configured for active-active failover, meaning each region services traffic at all times.

### Implementation 1A: Cross-Regional Omni Gateway

In this implementation:

- A single Omni Gateway has Omni Replicas distributed across multiple regions.

- Omni Gateway is registered once in Anypoint Platform and deployed across multiple regions and
  availability zones.

- Logs and metrics for each Omni Gateway are consolidated in Anypoint Platform.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- APIs deployed to the Gateway are available in all regions and availability zones.

- API configurations, including upstream services and policies are the same for all regions.
  Upstream services must be region-agnostic, meaning either the DNS is local or it lacks any
  reference to the region.

- If using Redis shared storage: The Redis cluster must be replicated across regions or Redis shared
  storage can’t be used. Redis replication is required when traffic isn’t region-specific.

- If using Redis shared storage: The only cross-regional traffic is Redis synchronization.

- If using distributed shared storage: No cross-region synchronization is needed.

In the following diagram, Omni Replicas in different regions and availability zones have distinct
Kubernetes deployments:

![A detailed view of implementation 1A, which contains the necessary services to support high availability in for Omni Replicas deployed in different regions](/mulesoft/current/en-us/gateway/latest/_images/high-availability-1a.png)

### Implementation 1B: Region-Specific Omni Gateway

In this implementation:

- Each region has a distinct Omni Gateway with all resources as independent entities.

- A separate Omni Gateway is registered for each region.

- Each region-specific API instance has distinct metrics, alerts, and logs in Anypoint Platform.

- Policies are region specific even if the configuration is similar across regions.

- The DNS service is configured for active-active failover to direct traffic to any region at all
  times.

- API deployments are specific to each Omni Gateway. For each API a region supports, you must deploy
  an API instance to the region’s Omni Gateway.

- API Groups can share contracts (access requests) across regions. An API Group might not be
  required for your configuration.

- If using Redis shared storage: Redis does not require synchronization.

- If using distributed shared storage: No cross-region synchronization is needed.

- There is no cross-regional traffic.

In the following diagram, all APIs are duplicated and don’t require identical configurations:

![A detailed view of implementation 1B, which contains the necessary services to support high availability for region-specific Omni Gateways](/mulesoft/current/en-us/gateway/latest/_images/high-availability-1b.png)

## Implementation 2: Disaster Recovery for APIs

This implementation is similar to
[Implementation 1A: Cross-Regional Omni Gateway](#implementation-1a). However, the DNS service is
active-passive, so the standby region only receives traffic if the primary region becomes unhealthy.
This implementation is less complex to configure than implementation 1A.

If using Redis shared storage, Redis synchronization isn’t required if a cache loss during failover
is acceptable. If using distributed shared storage, no synchronization is needed.

In the following diagram, Omni Replicas in different availability zones have distinct Kubernetes
deployments. Region B provides high availability but receives traffic only if region A is unhealthy:

![A detailed view of implementation 2, which contains the necessary services to enable disaster recovery for APIs on Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/high-availability-2.png)

## Implementation 3: Direct Traffic to the Closest Region

In both [Implementation 3A: Direct Traffic to APIs With the Same Policies](#implementation-3a) and
[Implementation 3B: Direct Traffic to APIs With the Different Policies](#implementation-3b), Omni
Gateway directs traffic to the most convenient region to reduce latency. Choose which implementation
according to your policy requirements.

### Implementation 3A: Direct Traffic to APIs With the Same Policies

This implementation is similar to
[Implementation 1A: Cross-Regional Omni Gateway](#implementation-1a) and has the same
considerations. However, if using Redis shared storage, Redis replication is not required because
requests are sent to specific regions. Configure high availability or disaster recovery zones in
each region to ensure API availability:

![A detailed view of implementation 3A, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/latest/_images/high-availability-3a.png)

### Implementation 3B: Direct Traffic to APIs With the Different Policies

This implementation is similar to
[Implementation 1B: Region-Specific Omni Gateway](#implementation-1b) and has the same
considerations. Deploy region-specific gateways and apply the necessary policies to the different
APIs. Configure high availability or disaster recovery zones in each region to ensure API
availability:

![A detailed view of implementation 3B, which contains the necessary services to route customer requests to the closest region](/mulesoft/current/en-us/gateway/latest/_images/high-availability-3b.png)

> [!NOTE] To apply SLA rate limiting across all regions, the rate limits must be the same for all
> regions. Use API groups to consolidate the contracts.

<!-- document id=54ca846ca2e501e0c48f8f685c71ec33b1528248fe35c6acab27002cca6bb0af url=/mulesoft/current/en-us/gateway/1.12/flex-security-best-practices.md -->

---
product: Omni Gateway
version: 1.12
---

# Self-Managed Flex Gateway Security Best Practices

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

This page provides best practices to ensure your Flex Gateway runtime deployment meets industry
standards.

Flex Gateway deployments consist of the runtime and control plane. Information such as configuration
data and logging is shared between Anypoint Platform in the control plane and Flex Gateway in the
runtime plane via mTLS communication. In the runtime layer, Flex Gateway orchestrates the incoming
traffic and protects the upstream service or API. Flex Gateway is registered with Anypoint Platform
by using a YAML registration file. Flex Gateway uses Redis shared storage to cache data to
communicate with other Flex Replicas and cache request data. This diagram demonstrates a Flex
Gateway deployment:

![security best practices](/mulesoft/current/en-us/gateway/1.12/_images/security-best-practices.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td><a href="#secure-flex-gateway-in-anypoint-platform">Secure Flex Gateway in Anypoint Platform</a></td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Protect your Flex Gateway:<div><ol type="a"><li><p><a href="#secure-flex-gateway-service-pods">Secure Flex Gateway Service Pods</a></p></li><li><p><a href="#update-your-flex-gateway">Update your Flex Gateway</a></p></li></ol></div></td></tr><tr><td><i data-value="3"></i><b>3</b></td><td><a href="#secure-the-flex-gateway-registration-resource">Secure the Flex Gateway Registration Resource</a></td></tr><tr><td><i data-value="4"></i><b>4</b></td><td><a href="#renew-the-flex-certificate">Renew the Flex Certificate</a></td></tr><tr><td><i data-value="5"></i><b>5</b></td><td><a href="#avoid-logging-payload-data">Avoid Logging Payload Data</a></td></tr><tr><td><i data-value="6"></i><b>6</b></td><td><a href="#secure-redis-shared-storage">Secure Redis Shared Storage</a></td></tr><tr><td><i data-value="7"></i><b>7</b></td><td><a href="#protect-the-flow-of-incoming-traffic">Protect the Flow of Incoming Traffic (API Consumer to Flex Gateway)</a></td></tr><tr><td><i data-value="8"></i><b>8</b></td><td><a href="#protect-the-upstream-service">Protect the Upstream Service (Flex Gateway to API Provider)</a>:<div><ol type="a"><li><p><a href="#protect-services-available-locally-to-flex-gateway">Protect Services Available Locally to Flex Gateway</a></p></li><li><p><a href="#protect-external-services">Protect External Services</a></p></li></ol></div></td></tr><tr><td><i data-value="9"></i><b>9</b></td><td><a href="#perform-regular-testing">Perform Regular Testing</a></td></tr></tbody></table>

> [!NOTE] Guidelines on this page are applicable to all Flex Gateway runtime environments, but
> diagrams are only provided for Kubernetes.

## Secure Flex Gateway in Anypoint Platform

Always apply the principle of least privilege to Flex Gateways in Anypoint Platform. Users who have
access to Flex Gateway are able to view Flex Gateway configuration details and logs. Use users and
team permissions to limit access to Flex Gateways to only those users who maintain the runtime.
Provide read-only access except for users who deploy or manage the gateway configuration.

To learn how to manage access, see [Access Management Overview](https://docs.mulesoft.com/access-management/).

## Secure the Flex Gateway Registration Resource

Flex Gateway stores registration information locally. This registration resource contains the
certificate the Flex Replica uses to communicate and authenticate itself with Anypoint Platform.
Flex Gateway communicates with Anypoint Platform via mTLS.

Restrict access to the registration resource to ensure there’s no unauthorized execution of
replicas. Specifically:

- Ensure you encrypt secrets at rest and you enforce least privilege access for the registration
  resource secret.

- Store sensitive data, such as credentials and API keys, in secure vaults, for example, AWS Secrets
  Manager, Azure Key Vault, or HashiCorp Vault.

- Avoid hardcoding secrets and only use environment variables for non-sensitive configurations.

- Encrypt sensitive information in configuration files.

For best practices for Kubernetes deployments, see
[Good practices for Kubernetes Secrets](https://kubernetes.io/docs/concepts/security/secrets-good-practices/).

## Renew the Flex Certificate

Anypoint Flex Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This
certificate is generated when you register Flex Gateway. Renew the certificate before its expiration
date to ensure the runtime can connect to the control plane.

To learn how to renew your registration, see
[Renew Self-Managed Flex Gateway Registration](https://docs.mulesoft.com/gateway/1.12/flex-gateway-renew-certificate).

## Update your Flex Gateway

MuleSoft regularly provides security updates for Flex Gateway. Keep your Flex Gateway updated to the
latest version to address vulnerabilities. To reduce the risk of incompatibilities, follow safe
change processes and upgrade sandbox runtimes ahead of production.

To learn more about how to update your Flex Gateway, see
[Upgrade Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-upgrade).

## Avoid Logging Payload Data

Runtime logs are available in the runtime layer through the `stdout` of the Flex Gateway pods and in
the Anypoint control plane for Connected Mode.

To ensure compromised runtime logs don’t leak client information, avoid logging payload data in
runtime logs.

If using other third party monitoring and analytics platforms, ensure you consider then in access
reviews.

## Secure Flex Gateway Service Pods

Restrict access to Flex Gateway runtime pods to ensure unauthorized personel cannot access Flex
Gateway configuration data or tamper with the runtime.

For Kubernetes deployments, restrict access to command execution in the pod by using Kubernetes
Role-based access control (RBAC). For more information, see
[Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

In non-Kubernetes deployments, restrict access to the Flex Gateway virtual machine to open sessions.

## Secure Redis Shared Storage

Flex Gateway uses Redis shared storage to cache request data and runtime configurations in Connected
Mode only. An unauthorized user can obtain cached configuration data, such as Flex configuration or
request processing caches, and can disrupt the runtime. You must secure the Redis service to prevent
unauthorized access.

To secure the Redis shared storage, see
[Redis Recommended security practices](https://redis.io/docs/latest/operate/rs/security/recommended-security-practices/).
Enable access control to limit Redis access from sources other than Flex Gateway. Deploy the Redis
as close as possible to the Flex Gateway deployment to further limit vulnerabilities.

## Protect the Flow of Incoming Traffic (API Consumer to Flex Gateway)

How you protect the flow of incoming traffic from external attacks is dependent on the source of
incoming traffic.

For requests coming from the public internet, configure a first line of defense system to intercept
the traffic before it reaches the Flex Gateway. Flex Gateway provides API-level protection but
relies on other general protections for the first line of defense. Ensure you have these
protections:

- Network level protections, like ACLs and DNS Firewalls. Cloud providers and third parties
  typically provide these protections.

- First line application level protections, such as threat protection against DDoS attacks and Web
  Application Firewall.

> [!NOTE] For guidelines on handling incoming requests from external sources, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4).

### Terminate External TLS at Point of Entry

To enable the firewall to perform L7 traffic security inspections, terminate external TLS
connections at the firewall level. A valid Certificate Authority (CA) that’s recognized by the
consumer typically provides the certificates at this point of entry.

Use a separate set of certificates for internal communication between the firewall, Flex Gateway,
and other services in the infrastructure. For this communication, use mTLS security with both
certificates issued by an internal authority or PKI.

Certificates exposed to the internet are never used internally, and certificates that are used
internally are never exposed to the internet. Separating internal and external certificates prevents
potential leakage of the internal credentials.

You can use Flex Gateway at both the runtime environment ingress layer or at the inner environment
layer. For Flex Gateways at the ingress layer, limit the gateways' scope to TLS termination,
routing, and other basic protections. Push more CPU and memory intensive operations to inner Flex
Gateways.

### Protect APIs by Using Policies

Apply policies to enhance API protections. Flex Gateway offers
[Included Policies](https://docs.mulesoft.com/gateway/1.12/policies-included-directory) and enables you to develop custom policies by using
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

### Govern APIs by Using API Governance

Use [Anypoint API Governance](https://docs.mulesoft.com/api-governance/) to ensure you design and deploy APIs in line
with MuleSoft, industry, and your organization’s best practices.

## Protect the Upstream Service (Flex Gateway to API Provider)

How you protect the flow of traffic from Flex to the upstream service is dependent on the location
of the upstream service.

### Protect Services Available Locally to Flex Gateway

Services that share the same network as Flex Gateway typically have lower security restrictions.

The organization must define whether plain or TLS connections are in place. If using TLS, configure
mTLS via Flex Gateway Outbound TLS contexts. To learn more about configuring TLS, see xref:

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config)

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config)

To protect the upstream service from other services in the same network, configure the upstream
service to accept traffic only from Flex Gateway. For Kubernetes, configure this using Network
Policies.

> [!NOTE] For guidelines on communicating to an internal upstream service, see
> [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1)
> and
> [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3).

### Protect External Services

When protecting external services not in the same network, connect to the service using mTLS
communication. Configure a trusted network link, such as private VPC, between the networks to enable
Flex Gateway to securely access the upstream service without exposing the service to the public
internet.

> [!NOTE] For guidelines on communicating to an external upstream service, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4).

## Perform Regular Testing

Perform regular penetration and vulnerability tests to identify new or regressed issues in your Flex
Gateway deployment and exposed APIs. Consider these security aspects when testing:

- User access controls in Anypoint Platform that enable access to Flex registration in Runtime
  Manager, logs in Anypoint Monitoring, and APIs in API Manager.

- Access to the deployed Flex Gateway that affects its function or data.

- Access to any configuration files used by the Flex runtime, especially the registration file.

- Access to the Redis shared storage service.

- Access to APIs deployed on the Flex Gateway.

- Access to the upstream services protected by the Flex Gateway APIs.

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc-overview)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.12/flex-architecture-shared-storage)

<!-- document id=3077ae409acef9353fbc1c414639dd09af77ec542b587319b14100bbe9f80299 url=/mulesoft/current/en-us/gateway/1.9/flex-security-best-practices.md -->

---
product: Omni Gateway
version: 1.9
---

# Self-Managed Flex Gateway Security Best Practices

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

This page provides best practices to ensure your Flex Gateway runtime deployment meets industry
standards.

Flex Gateway deployments consist of the runtime and control plane. Information such as configuration
data and logging is shared between Anypoint Platform in the control plane and Flex Gateway in the
runtime plane via mTLS communication. In the runtime layer, Flex Gateway orchestrates the incoming
traffic and protects the upstream service or API. Flex Gateway is registered with Anypoint Platform
by using a YAML registration file. Flex Gateway uses Redis shared storage to cache data to
communicate with other Flex Replicas and cache request data. This diagram demonstrates a Flex
Gateway deployment:

![security best practices](/mulesoft/current/en-us/gateway/1.9/_images/security-best-practices.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td><a href="#secure-flex-gateway-in-anypoint-platform">Secure Flex Gateway in Anypoint Platform</a></td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Protect your Flex Gateway:<div><ol type="a"><li><p><a href="#secure-flex-gateway-service-pods">Secure Flex Gateway Service Pods</a></p></li><li><p><a href="#update-your-flex-gateway">Update your Flex Gateway</a></p></li></ol></div></td></tr><tr><td><i data-value="3"></i><b>3</b></td><td><a href="#secure-the-flex-gateway-registration-resource">Secure the Flex Gateway Registration Resource</a></td></tr><tr><td><i data-value="4"></i><b>4</b></td><td><a href="#renew-the-flex-certificate">Renew the Flex Certificate</a></td></tr><tr><td><i data-value="5"></i><b>5</b></td><td><a href="#avoid-logging-payload-data">Avoid Logging Payload Data</a></td></tr><tr><td><i data-value="6"></i><b>6</b></td><td><a href="#secure-redis-shared-storage">Secure Redis Shared Storage</a></td></tr><tr><td><i data-value="7"></i><b>7</b></td><td><a href="#protect-the-flow-of-incoming-traffic">Protect the Flow of Incoming Traffic (API Consumer to Flex Gateway)</a></td></tr><tr><td><i data-value="8"></i><b>8</b></td><td><a href="#protect-the-upstream-service">Protect the Upstream Service (Flex Gateway to API Provider)</a>:<div><ol type="a"><li><p><a href="#protect-services-available-locally-to-flex-gateway">Protect Services Available Locally to Flex Gateway</a></p></li><li><p><a href="#protect-external-services">Protect External Services</a></p></li></ol></div></td></tr><tr><td><i data-value="9"></i><b>9</b></td><td><a href="#perform-regular-testing">Perform Regular Testing</a></td></tr></tbody></table>

> [!NOTE] Guidelines on this page are applicable to all Flex Gateway runtime environments, but
> diagrams are only provided for Kubernetes.

## Secure Flex Gateway in Anypoint Platform

Always apply the principle of least privilege to Flex Gateways in Anypoint Platform. Users who have
access to Flex Gateway are able to view Flex Gateway configuration details and logs. Use users and
team permissions to limit access to Flex Gateways to only those users who maintain the runtime.
Provide read-only access except for users who deploy or manage the gateway configuration.

To learn how to manage access, see [Access Management Overview](https://docs.mulesoft.com/access-management/).

## Secure the Flex Gateway Registration Resource

Flex Gateway stores registration information locally. This registration resource contains the
certificate the Flex Replica uses to communicate and authenticate itself with Anypoint Platform.
Flex Gateway communicates with Anypoint Platform via mTLS.

Restrict access to the registration resource to ensure there’s no unauthorized execution of
replicas. Specifically:

- Ensure you encrypt secrets at rest and you enforce least privilege access for the registration
  resource secret.

- Store sensitive data, such as credentials and API keys, in secure vaults, for example, AWS Secrets
  Manager, Azure Key Vault, or HashiCorp Vault.

- Avoid hardcoding secrets and only use environment variables for non-sensitive configurations.

- Encrypt sensitive information in configuration files.

For best practices for Kubernetes deployments, see
[Good practices for Kubernetes Secrets](https://kubernetes.io/docs/concepts/security/secrets-good-practices/).

## Renew the Flex Certificate

Anypoint Flex Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This
certificate is generated when you register Flex Gateway. Renew the certificate before its expiration
date to ensure the runtime can connect to the control plane.

To learn how to renew your registration, see
[Renew Self-Managed Flex Gateway Registration](https://docs.mulesoft.com/gateway/1.9/flex-gateway-renew-certificate).

## Update your Flex Gateway

MuleSoft regularly provides security updates for Flex Gateway. Keep your Flex Gateway updated to the
latest version to address vulnerabilities. To reduce the risk of incompatibilities, follow safe
change processes and upgrade sandbox runtimes ahead of production.

To learn more about how to update your Flex Gateway, see
[Upgrade Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-upgrade).

## Avoid Logging Payload Data

Runtime logs are available in the runtime layer through the `stdout` of the Flex Gateway pods and in
the Anypoint control plane for Connected Mode.

To ensure compromised runtime logs don’t leak client information, avoid logging payload data in
runtime logs.

If using other third party monitoring and analytics platforms, ensure you consider then in access
reviews.

## Secure Flex Gateway Service Pods

Restrict access to Flex Gateway runtime pods to ensure unauthorized personel cannot access Flex
Gateway configuration data or tamper with the runtime.

For Kubernetes deployments, restrict access to command execution in the pod by using Kubernetes
Role-based access control (RBAC). For more information, see
[Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

In non-Kubernetes deployments, restrict access to the Flex Gateway virtual machine to open sessions.

## Secure Redis Shared Storage

Flex Gateway uses Redis shared storage to cache request data and runtime configurations in Connected
Mode only. An unauthorized user can obtain cached configuration data, such as Flex configuration or
request processing caches, and can disrupt the runtime. You must secure the Redis service to prevent
unauthorized access.

To secure the Redis shared storage, see
[Redis Recommended security practices](https://redis.io/docs/latest/operate/rs/security/recommended-security-practices/).
Enable access control to limit Redis access from sources other than Flex Gateway. Deploy the Redis
as close as possible to the Flex Gateway deployment to further limit vulnerabilities.

## Protect the Flow of Incoming Traffic (API Consumer to Flex Gateway)

How you protect the flow of incoming traffic from external attacks is dependent on the source of
incoming traffic.

For requests coming from the public internet, configure a first line of defense system to intercept
the traffic before it reaches the Flex Gateway. Flex Gateway provides API-level protection but
relies on other general protections for the first line of defense. Ensure you have these
protections:

- Network level protections, like ACLs and DNS Firewalls. Cloud providers and third parties
  typically provide these protections.

- First line application level protections, such as threat protection against DDoS attacks and Web
  Application Firewall.

> [!NOTE] For guidelines on handling incoming requests from external sources, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4).

### Terminate External TLS at Point of Entry

To enable the firewall to perform L7 traffic security inspections, terminate external TLS
connections at the firewall level. A valid Certificate Authority (CA) that’s recognized by the
consumer typically provides the certificates at this point of entry.

Use a separate set of certificates for internal communication between the firewall, Flex Gateway,
and other services in the infrastructure. For this communication, use mTLS security with both
certificates issued by an internal authority or PKI.

Certificates exposed to the internet are never used internally, and certificates that are used
internally are never exposed to the internet. Separating internal and external certificates prevents
potential leakage of the internal credentials.

You can use Flex Gateway at both the runtime environment ingress layer or at the inner environment
layer. For Flex Gateways at the ingress layer, limit the gateways' scope to TLS termination,
routing, and other basic protections. Push more CPU and memory intensive operations to inner Flex
Gateways.

### Protect APIs by Using Policies

Apply policies to enhance API protections. Flex Gateway offers
[Included Policies](https://docs.mulesoft.com/gateway/1.9/policies-included-directory) and enables you to develop custom policies by using
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

### Govern APIs by Using API Governance

Use [Anypoint API Governance](https://docs.mulesoft.com/api-governance/) to ensure you design and deploy APIs in line
with MuleSoft, industry, and your organization’s best practices.

## Protect the Upstream Service (Flex Gateway to API Provider)

How you protect the flow of traffic from Flex to the upstream service is dependent on the location
of the upstream service.

### Protect Services Available Locally to Flex Gateway

Services that share the same network as Flex Gateway typically have lower security restrictions.

The organization must define whether plain or TLS connections are in place. If using TLS, configure
mTLS via Flex Gateway Outbound TLS contexts. To learn more about configuring TLS, see xref:

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config)

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config)

To protect the upstream service from other services in the same network, configure the upstream
service to accept traffic only from Flex Gateway. For Kubernetes, configure this using Network
Policies.

> [!NOTE] For guidelines on communicating to an internal upstream service, see
> [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1)
> and
> [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3).

### Protect External Services

When protecting external services not in the same network, connect to the service using mTLS
communication. Configure a trusted network link, such as private VPC, between the networks to enable
Flex Gateway to securely access the upstream service without exposing the service to the public
internet.

> [!NOTE] For guidelines on communicating to an external upstream service, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4).

## Perform Regular Testing

Perform regular penetration and vulnerability tests to identify new or regressed issues in your Flex
Gateway deployment and exposed APIs. Consider these security aspects when testing:

- User access controls in Anypoint Platform that enable access to Flex registration in Runtime
  Manager, logs in Anypoint Monitoring, and APIs in API Manager.

- Access to the deployed Flex Gateway that affects its function or data.

- Access to any configuration files used by the Flex runtime, especially the registration file.

- Access to the Redis shared storage service.

- Access to APIs deployed on the Flex Gateway.

- Access to the upstream services protected by the Flex Gateway APIs.

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc-overview)

- [Shared Storage Models](https://docs.mulesoft.com/gateway/1.9/flex-architecture-shared-storage)

<!-- document id=d19dfe8a29099485a695bbfcb4069ef36c453ba4b71a7b69857c23cee0557631 url=/mulesoft/current/en-us/gateway/1.13/security-best-practices.md -->

---
product: Omni Gateway
version: 1.13
---

# Self-Managed Omni Gateway Security Best Practices

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

This page provides best practices to ensure your Omni Gateway runtime deployment meets industry
standards.

Omni Gateway deployments consist of the runtime and control plane. Information such as configuration
data and logging is shared between Anypoint Platform in the control plane and Omni Gateway in the
runtime plane via mTLS communication. In the runtime layer, Omni Gateway orchestrates the incoming
traffic and protects the upstream service or API. Omni Gateway is registered with Anypoint Platform
by using a YAML registration file. Omni Gateway can use Redis shared storage to cache data to
communicate with other Omni Replicas and cache request data. This diagram demonstrates an Omni
Gateway deployment:

![security best practices](/mulesoft/current/en-us/gateway/1.13/_images/security-best-practices.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td><a href="#secure-flex-gateway-in-anypoint-platform">Secure Omni Gateway in Anypoint Platform</a></td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Protect your Omni Gateway:<div><ol type="a"><li><p><a href="#secure-flex-gateway-service-pods">Secure Omni Gateway Service Pods</a></p></li><li><p><a href="#update-your-flex-gateway">Update your Omni Gateway</a></p></li></ol></div></td></tr><tr><td><i data-value="3"></i><b>3</b></td><td><a href="#secure-the-flex-gateway-registration-resource">Secure the Omni Gateway Registration Resource</a></td></tr><tr><td><i data-value="4"></i><b>4</b></td><td><a href="#renew-the-flex-certificate">Renew the Omni Certificate</a></td></tr><tr><td><i data-value="5"></i><b>5</b></td><td><a href="#avoid-logging-payload-data">Avoid Logging Payload Data</a></td></tr><tr><td><i data-value="6"></i><b>6</b></td><td><a href="#secure-redis-shared-storage">Secure Redis Shared Storage</a></td></tr><tr><td><i data-value="7"></i><b>7</b></td><td><a href="#protect-the-flow-of-incoming-traffic">Protect the Flow of Incoming Traffic (API Consumer to Omni Gateway)</a></td></tr><tr><td><i data-value="8"></i><b>8</b></td><td><a href="#protect-the-upstream-service">Protect the Upstream Service (Omni Gateway to API Provider)</a>:<div><ol type="a"><li><p><a href="#protect-services-available-locally-to-flex-gateway">Protect Services Available Locally to Omni Gateway</a></p></li><li><p><a href="#protect-external-services">Protect External Services</a></p></li></ol></div></td></tr><tr><td><i data-value="9"></i><b>9</b></td><td><a href="#perform-regular-testing">Perform Regular Testing</a></td></tr></tbody></table>

> [!NOTE] Guidelines on this page are applicable to all Omni Gateway runtime environments, but
> diagrams are only provided for Kubernetes.

## Secure Omni Gateway in Anypoint Platform

Always apply the principle of least privilege to Omni Gateways in Anypoint Platform. Users who have
access to Omni Gateway are able to view Omni Gateway configuration details and logs. Use users and
team permissions to limit access to Omni Gateways to only those users who maintain the runtime.
Provide read-only access except for users who deploy or manage the gateway configuration.

To learn how to manage access, see [Access Management Overview](https://docs.mulesoft.com/access-management/).

## Secure the Omni Gateway Registration Resource

Omni Gateway stores registration information locally. This registration resource contains the
certificate the Omni Replica uses to communicate and authenticate itself with Anypoint Platform.
Omni Gateway communicates with Anypoint Platform via mTLS.

Restrict access to the registration resource to ensure there’s no unauthorized execution of
replicas. Specifically:

- Ensure you encrypt secrets at rest and you enforce least privilege access for the registration
  resource secret.

- Store sensitive data, such as credentials and API keys, in secure vaults, for example, AWS Secrets
  Manager, Azure Key Vault, or HashiCorp Vault.

- Avoid hardcoding secrets and only use environment variables for non-sensitive configurations.

- Encrypt sensitive information in configuration files.

For best practices for Kubernetes deployments, see
[Good practices for Kubernetes Secrets](https://kubernetes.io/docs/concepts/security/secrets-good-practices/).

## Renew the Omni Certificate

Omni Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This certificate
is generated when you register Omni Gateway. Renew the certificate before its expiration date to
ensure the runtime can connect to the control plane.

To learn how to renew your registration, see
[Renew Self-Managed Omni Gateway Registration](https://docs.mulesoft.com/gateway/1.13/gateway-renew-certificate).

## Update your Omni Gateway

MuleSoft regularly provides security updates for Omni Gateway. Keep your Omni Gateway updated to the
latest version to address vulnerabilities. To reduce the risk of incompatibilities, follow safe
change processes and upgrade sandbox runtimes ahead of production.

To learn more about how to update your Omni Gateway, see
[Upgrade Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-upgrade).

## Avoid Logging Payload Data

Runtime logs are available in the runtime layer through the `stdout` of the Omni Gateway pods and in
the Anypoint control plane for Connected Mode.

To ensure compromised runtime logs don’t leak client information, avoid logging payload data in
runtime logs.

If using other third party monitoring and analytics platforms, ensure you consider then in access
reviews.

## Secure Omni Gateway Service Pods

Restrict access to Omni Gateway runtime pods to ensure unauthorized personel cannot access Omni
Gateway configuration data or tamper with the runtime.

For Kubernetes deployments, restrict access to command execution in the pod by using Kubernetes
Role-based access control (RBAC). For more information, see
[Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

In non-Kubernetes deployments, restrict access to the Omni Gateway virtual machine to open sessions.

## Secure Redis Shared Storage

Omni Gateway uses Redis shared storage to cache request data and runtime configurations in Connected
Mode only. An unauthorized user can obtain cached configuration data, such as Omni configuration or
request processing caches, and can disrupt the runtime. You must secure the Redis service to prevent
unauthorized access.

To secure the Redis shared storage, see
[Redis Recommended security practices](https://redis.io/docs/latest/operate/rs/security/recommended-security-practices/).
Enable access control to limit Redis access from sources other than Omni Gateway. Deploy the Redis
as close as possible to the Omni Gateway deployment to further limit vulnerabilities.

## Protect the Flow of Incoming Traffic (API Consumer to Omni Gateway)

How you protect the flow of incoming traffic from external attacks is dependent on the source of
incoming traffic.

For requests coming from the public internet, configure a first line of defense system to intercept
the traffic before it reaches the Omni Gateway. Omni Gateway provides API-level protection but
relies on other general protections for the first line of defense. Ensure you have these
protections:

- Network level protections, like ACLs and DNS Firewalls. Cloud providers and third parties
  typically provide these protections.

- First line application level protections, such as threat protection against DDoS attacks and Web
  Application Firewall.

> [!NOTE] For guidelines on handling incoming requests from external sources, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4).

### Terminate External TLS at Point of Entry

To enable the firewall to perform L7 traffic security inspections, terminate external TLS
connections at the firewall level. A valid Certificate Authority (CA) that’s recognized by the
consumer typically provides the certificates at this point of entry.

Use a separate set of certificates for internal communication between the firewall, Omni Gateway,
and other services in the infrastructure. For this communication, use mTLS security with both
certificates issued by an internal authority or PKI.

Certificates exposed to the internet are never used internally, and certificates that are used
internally are never exposed to the internet. Separating internal and external certificates prevents
potential leakage of the internal credentials.

You can use Omni Gateway at both the runtime environment ingress layer or at the inner environment
layer. For Omni Gateways at the ingress layer, limit the gateways' scope to TLS termination,
routing, and other basic protections. Push more CPU and memory intensive operations to inner Omni
Gateways.

### Protect APIs by Using Policies

Apply policies to enhance API protections. Omni Gateway offers
[Included Policies](https://docs.mulesoft.com/gateway/1.13/policies-included-directory) and enables you to develop custom policies by using
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

### Govern APIs by Using API Governance

Use [Anypoint API Governance](https://docs.mulesoft.com/api-governance/) to ensure you design and deploy APIs in line
with MuleSoft, industry, and your organization’s best practices.

## Protect the Upstream Service (Omni Gateway to API Provider)

How you protect the flow of traffic from Omni to the upstream service is dependent on the location
of the upstream service.

### Protect Services Available Locally to Omni Gateway

Services that share the same network as Omni Gateway typically have lower security restrictions.

The organization must define whether plain or TLS connections are in place. If using TLS, configure
mTLS via Omni Gateway Outbound TLS contexts. To learn more about configuring TLS, see xref:

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config)

To protect the upstream service from other services in the same network, configure the upstream
service to accept traffic only from Omni Gateway. For Kubernetes, configure this using Network
Policies.

> [!NOTE] For guidelines on communicating to an internal upstream service, see
> [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1)
> and
> [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3).

### Protect External Services

When protecting external services not in the same network, connect to the service using mTLS
communication. Configure a trusted network link, such as private VPC, between the networks to enable
Omni Gateway to securely access the upstream service without exposing the service to the public
internet.

> [!NOTE] For guidelines on communicating to an external upstream service, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4).

## Perform Regular Testing

Perform regular penetration and vulnerability tests to identify new or regressed issues in your Omni
Gateway deployment and exposed APIs. Consider these security aspects when testing:

- User access controls in Anypoint Platform that enable access to Omni registration in Runtime
  Manager, logs in Anypoint Monitoring, and APIs in API Manager.

- Access to the deployed Omni Gateway that affects its function or data.

- Access to any configuration files used by the Omni runtime, especially the registration file.

- Access to the Redis shared storage service.

- Access to APIs deployed on the Omni Gateway.

- Access to the upstream services protected by the Omni Gateway APIs.

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc-overview)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-shared-storage)

<!-- document id=d3b799c94e46aa979e451c67c1c676fcf61475204e0ca94bdf269e03fbe38016 url=/mulesoft/current/en-us/gateway/latest/security-best-practices.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Self-Managed Omni Gateway Security Best Practices

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

This page provides best practices to ensure your Omni Gateway runtime deployment meets industry
standards.

Omni Gateway deployments consist of the runtime and control plane. Information such as configuration
data and logging is shared between Anypoint Platform in the control plane and Omni Gateway in the
runtime plane via mTLS communication. In the runtime layer, Omni Gateway orchestrates the incoming
traffic and protects the upstream service or API. Omni Gateway is registered with Anypoint Platform
by using a YAML registration file. Omni Gateway can use Redis shared storage to cache data to
communicate with other Omni Replicas and cache request data. This diagram demonstrates an Omni
Gateway deployment:

![security best practices](/mulesoft/current/en-us/gateway/latest/_images/security-best-practices.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td><a href="#secure-flex-gateway-in-anypoint-platform">Secure Omni Gateway in Anypoint Platform</a></td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Protect your Omni Gateway:<div><ol type="a"><li><p><a href="#secure-flex-gateway-service-pods">Secure Omni Gateway Service Pods</a></p></li><li><p><a href="#update-your-flex-gateway">Update your Omni Gateway</a></p></li></ol></div></td></tr><tr><td><i data-value="3"></i><b>3</b></td><td><a href="#secure-the-flex-gateway-registration-resource">Secure the Omni Gateway Registration Resource</a></td></tr><tr><td><i data-value="4"></i><b>4</b></td><td><a href="#renew-the-flex-certificate">Renew the Omni Certificate</a></td></tr><tr><td><i data-value="5"></i><b>5</b></td><td><a href="#avoid-logging-payload-data">Avoid Logging Payload Data</a></td></tr><tr><td><i data-value="6"></i><b>6</b></td><td><a href="#secure-redis-shared-storage">Secure Redis Shared Storage</a></td></tr><tr><td><i data-value="7"></i><b>7</b></td><td><a href="#protect-the-flow-of-incoming-traffic">Protect the Flow of Incoming Traffic (API Consumer to Omni Gateway)</a></td></tr><tr><td><i data-value="8"></i><b>8</b></td><td><a href="#protect-the-upstream-service">Protect the Upstream Service (Omni Gateway to API Provider)</a>:<div><ol type="a"><li><p><a href="#protect-services-available-locally-to-flex-gateway">Protect Services Available Locally to Omni Gateway</a></p></li><li><p><a href="#protect-external-services">Protect External Services</a></p></li></ol></div></td></tr><tr><td><i data-value="9"></i><b>9</b></td><td><a href="#perform-regular-testing">Perform Regular Testing</a></td></tr></tbody></table>

> [!NOTE] Guidelines on this page are applicable to all Omni Gateway runtime environments, but
> diagrams are only provided for Kubernetes.

## Secure Omni Gateway in Anypoint Platform

Always apply the principle of least privilege to Omni Gateways in Anypoint Platform. Users who have
access to Omni Gateway are able to view Omni Gateway configuration details and logs. Use users and
team permissions to limit access to Omni Gateways to only those users who maintain the runtime.
Provide read-only access except for users who deploy or manage the gateway configuration.

To learn how to manage access, see [Access Management Overview](https://docs.mulesoft.com/access-management/).

## Secure the Omni Gateway Registration Resource

Omni Gateway stores registration information locally. This registration resource contains the
certificate the Omni Replica uses to communicate and authenticate itself with Anypoint Platform.
Omni Gateway communicates with Anypoint Platform via mTLS.

Restrict access to the registration resource to ensure there’s no unauthorized execution of
replicas. Specifically:

- Ensure you encrypt secrets at rest and you enforce least privilege access for the registration
  resource secret.

- Store sensitive data, such as credentials and API keys, in secure vaults, for example, AWS Secrets
  Manager, Azure Key Vault, or HashiCorp Vault.

- Avoid hardcoding secrets and only use environment variables for non-sensitive configurations.

- Encrypt sensitive information in configuration files.

For best practices for Kubernetes deployments, see
[Good practices for Kubernetes Secrets](https://kubernetes.io/docs/concepts/security/secrets-good-practices/).

## Renew the Omni Certificate

Omni Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This certificate
is generated when you register Omni Gateway. Renew the certificate before its expiration date to
ensure the runtime can connect to the control plane.

To learn how to renew your registration, see
[Renew Self-Managed Omni Gateway Registration](https://docs.mulesoft.com/gateway/latest/gateway-renew-certificate).

## Update your Omni Gateway

MuleSoft regularly provides security updates for Omni Gateway. Keep your Omni Gateway updated to the
latest version to address vulnerabilities. To reduce the risk of incompatibilities, follow safe
change processes and upgrade sandbox runtimes ahead of production.

To learn more about how to update your Omni Gateway, see
[Upgrade Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-upgrade).

## Avoid Logging Payload Data

Runtime logs are available in the runtime layer through the `stdout` of the Omni Gateway pods and in
the Anypoint control plane for Connected Mode.

To ensure compromised runtime logs don’t leak client information, avoid logging payload data in
runtime logs.

If using other third party monitoring and analytics platforms, ensure you consider then in access
reviews.

## Secure Omni Gateway Service Pods

Restrict access to Omni Gateway runtime pods to ensure unauthorized personel cannot access Omni
Gateway configuration data or tamper with the runtime.

For Kubernetes deployments, restrict access to command execution in the pod by using Kubernetes
Role-based access control (RBAC). For more information, see
[Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

In non-Kubernetes deployments, restrict access to the Omni Gateway virtual machine to open sessions.

## Secure Redis Shared Storage

Omni Gateway uses Redis shared storage to cache request data and runtime configurations in Connected
Mode only. An unauthorized user can obtain cached configuration data, such as Omni configuration or
request processing caches, and can disrupt the runtime. You must secure the Redis service to prevent
unauthorized access.

To secure the Redis shared storage, see
[Redis Recommended security practices](https://redis.io/docs/latest/operate/rs/security/recommended-security-practices/).
Enable access control to limit Redis access from sources other than Omni Gateway. Deploy the Redis
as close as possible to the Omni Gateway deployment to further limit vulnerabilities.

## Protect the Flow of Incoming Traffic (API Consumer to Omni Gateway)

How you protect the flow of incoming traffic from external attacks is dependent on the source of
incoming traffic.

For requests coming from the public internet, configure a first line of defense system to intercept
the traffic before it reaches the Omni Gateway. Omni Gateway provides API-level protection but
relies on other general protections for the first line of defense. Ensure you have these
protections:

- Network level protections, like ACLs and DNS Firewalls. Cloud providers and third parties
  typically provide these protections.

- First line application level protections, such as threat protection against DDoS attacks and Web
  Application Firewall.

> [!NOTE] For guidelines on handling incoming requests from external sources, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4).

### Terminate External TLS at Point of Entry

To enable the firewall to perform L7 traffic security inspections, terminate external TLS
connections at the firewall level. A valid Certificate Authority (CA) that’s recognized by the
consumer typically provides the certificates at this point of entry.

Use a separate set of certificates for internal communication between the firewall, Omni Gateway,
and other services in the infrastructure. For this communication, use mTLS security with both
certificates issued by an internal authority or PKI.

Certificates exposed to the internet are never used internally, and certificates that are used
internally are never exposed to the internet. Separating internal and external certificates prevents
potential leakage of the internal credentials.

You can use Omni Gateway at both the runtime environment ingress layer or at the inner environment
layer. For Omni Gateways at the ingress layer, limit the gateways' scope to TLS termination,
routing, and other basic protections. Push more CPU and memory intensive operations to inner Omni
Gateways.

### Protect APIs by Using Policies

Apply policies to enhance API protections. Omni Gateway offers
[Included Policies](https://docs.mulesoft.com/gateway/latest/policies-included-directory) and enables you to develop custom policies by using
[Omni Gateway Policy Development Kit (PDK) Overview](https://docs.mulesoft.com/pdk/latest/policies-pdk-overview).

### Govern APIs by Using API Governance

Use [Anypoint API Governance](https://docs.mulesoft.com/api-governance/) to ensure you design and deploy APIs in line
with MuleSoft, industry, and your organization’s best practices.

## Protect the Upstream Service (Omni Gateway to API Provider)

How you protect the flow of traffic from Omni to the upstream service is dependent on the location
of the upstream service.

### Protect Services Available Locally to Omni Gateway

Services that share the same network as Omni Gateway typically have lower security restrictions.

The organization must define whether plain or TLS connections are in place. If using TLS, configure
mTLS via Omni Gateway Outbound TLS contexts. To learn more about configuring TLS, see xref:

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tls-config)

To protect the upstream service from other services in the same network, configure the upstream
service to accept traffic only from Omni Gateway. For Kubernetes, configure this using Network
Policies.

> [!NOTE] For guidelines on communicating to an internal upstream service, see
> [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1)
> and
> [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3).

### Protect External Services

When protecting external services not in the same network, connect to the service using mTLS
communication. Configure a trusted network link, such as private VPC, between the networks to enable
Omni Gateway to securely access the upstream service without exposing the service to the public
internet.

> [!NOTE] For guidelines on communicating to an external upstream service, see
> [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2)
> and
> [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4).

## Perform Regular Testing

Perform regular penetration and vulnerability tests to identify new or regressed issues in your Omni
Gateway deployment and exposed APIs. Consider these security aspects when testing:

- User access controls in Anypoint Platform that enable access to Omni registration in Runtime
  Manager, logs in Anypoint Monitoring, and APIs in API Manager.

- Access to the deployed Omni Gateway that affects its function or data.

- Access to any configuration files used by the Omni runtime, especially the registration file.

- Access to the Redis shared storage service.

- Access to APIs deployed on the Omni Gateway.

- Access to the upstream services protected by the Omni Gateway APIs.

## See Also

- [Integration Use Cases](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc-overview)

- [Redis Shared Storage Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-shared-storage)

<!-- document id=4eb8492165a1d3f8b8d30feefc9bc6f588ad99b26c50df78346b10d2ca203f2d url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-set-up.md -->

---
product: Omni Gateway
version: 1.12
---

# Setting Up Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Setting up Anypoint Flex Gateway consists of installation and registration:

- [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-install)

  - Install in Linux. Download for Docker or Kubernetes.

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

  - Register in Connected Mode using an Anypoint username and password, a connected application, or
    a token.

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

  - Register in Local Mode using an Anypoint username and password, a connected application, or a
    token.

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.12/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-getting-started)

<!-- document id=9ff90a573e94ffb6a7c3e01c1a9bee96c24933a4d960b2e665b6b646dda36835 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-set-up.md -->

---
product: Omni Gateway
version: 1.9
---

# Setting Up Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Setting up Anypoint Flex Gateway consists of installation and registration:

- [Downloading Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-install)

  - Install in Linux. Download for Docker or Kubernetes.

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

  - Register in Connected Mode using an Anypoint username and password, a connected application, or
    a token.

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

  - Register in Local Mode using an Anypoint username and password, a connected application, or a
    token.

## See Also

- [Flex Gateway Overview](https://docs.mulesoft.com/gateway/1.9/)

- [Getting Started with Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-getting-started)

<!-- document id=00c9cd6de68aed02a1c760aff2d11a5c4beab99c31dc6c5145fcc0b38881bd95 url=/mulesoft/current/en-us/gateway/1.13/gateway-set-up.md -->

---
product: Omni Gateway
version: 1.13
---

# Setting Up Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Setting up Omni Gateway consists of installation and registration:

- [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/1.13/install)

  - Install in Linux. Download for Docker or Kubernetes.

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

  - Register in Connected Mode using an Anypoint username and password, a connected application, or
    a token.

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

  - Register in Local Mode using an Anypoint username and password, a connected application, or a
    token.

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/1.13/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-getting-started)

<!-- document id=e367b92b2e3d2fd4b569254a7c1b6d05b2280ce9418de3054da0c3a7f9390501 url=/mulesoft/current/en-us/gateway/latest/gateway-set-up.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Setting Up Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Setting up Omni Gateway consists of installation and registration:

- [Downloading Omni Gateway](https://docs.mulesoft.com/gateway/latest/install)

  - Install in Linux. Download for Docker or Kubernetes.

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

  - Register in Connected Mode using an Anypoint username and password, a connected application, or
    a token.

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

  - Register in Local Mode using an Anypoint username and password, a connected application, or a
    token.

## See Also

- [Omni Gateway Overview](https://docs.mulesoft.com/gateway/latest/)

- [Getting Started with Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-getting-started)

<!-- document id=dd91c2b02df820ba1a48386a23f87899ea4046450a91de44eee73c0cdb93842c url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-shared-storage.md -->

---
product: Omni Gateway
version: 1.12
---

# Shared Storage Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring shared storage, MuleSoft recommends placing the Redis shared storage service as
close to Flex Gateway as possible.

If the Redis shared storage service is available locally in the same cluster or the same Virtual
Private Cloud (VPC), a mutual authentication Transport Layer Security (mTLS) connection is not
required to communicate with the shared storage.

To configure the connection between Flex Gateway and the shared storage service, see:

- [Configure Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config)

- [Configure Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-shared-storage-config)

The following diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

You can place the Redis shared storage within the same Kubernetes cluster as Flex Gateway or
instantiated within the same VPC as Flex Gateway:

## Shared Storage in the Same Cluster

![The redis shared storage is in the same cluster as the Flex Gateway replicas](/mulesoft/current/en-us/gateway/1.12/_images/redis-same-cluster.png)

## Shared Storage in the Same VPC

![The redis shared storage is in the same VPC as the Flex Gateway replicas but is not in the same cluster](/mulesoft/current/en-us/gateway/1.12/_images/redis-same-vpc.png)

## See Also

- [Configure Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-shared-storage-config)

- [Configure Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-shared-storage-config)

- [Configuring Flex Gateway Configuration Caching in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-replica-caching)

<!-- document id=00da7297ca9f33fc12f8d87109d1eee77a8bb7e0a218fdb35a0f529f15c8c299 url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-shared-storage.md -->

---
product: Omni Gateway
version: 1.9
---

# Shared Storage Models

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring shared storage, MuleSoft recommends placing the Redis shared storage service as
close to Flex Gateway as possible.

If the Redis shared storage service is available locally in the same cluster or the same Virtual
Private Cloud (VPC), a mutual authentication Transport Layer Security (mTLS) connection is not
required to communicate with the shared storage.

To configure the connection between Flex Gateway and the shared storage service, see:

- [Configure Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config)

- [Configure Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-shared-storage-config)

The following diagrams use Kubernetes terminology, but you can extend the architecture to other
technology stacks that have the appropriate network controls applied.

You can place the Redis shared storage within the same Kubernetes cluster as Flex Gateway or
instantiated within the same VPC as Flex Gateway:

## Shared Storage in the Same Cluster

![The redis shared storage is in the same cluster as the Flex Gateway replicas](/mulesoft/current/en-us/gateway/1.9/_images/redis-same-cluster.png)

## Shared Storage in the Same VPC

![The redis shared storage is in the same VPC as the Flex Gateway replicas but is not in the same cluster](/mulesoft/current/en-us/gateway/1.9/_images/redis-same-vpc.png)

## See Also

- [Configure Shared Storage in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-shared-storage-config)

- [Configure Shared Storage in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-shared-storage-config)

- [Configuring Flex Gateway Configuration Caching in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-replica-caching)

<!-- document id=965ce297ac800358509ea14461b0c7cb9245027994a8fe796e752bc920474385 url=/mulesoft/current/en-us/gateway/1.12/policies-included-soap-schema-validation.md -->

---
product: Omni Gateway
version: 1.12
keywords: xml threat protection, api gateway, flex gateway, gateway, policy
---

# SOAP Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>SOAP Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming traffic against a specified WSDL schema</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.10.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>The policy returns a <code>400</code> for a client error or <code>500</code> for a server error. Error messages are defined by SOAP standard responses.</p></td></tr></tbody></table>

## Summary

> [!NOTE] The Schema Validation policy only supports SOAP 1.1 and 1.2 APIs.

Use the SOAP Schema Validation policy to block incoming requests that don’t conform to the the
defined WSDL schema. This policy prevents malformed or malicious SOAP messages from reaching the
backend and enforces contract compliance between clients and services.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: soap-validation config: wsdlUrl: <string> // REQUIRED encoding: <string> //
REQUIRED, default 'UTF-8' serviceName: <string> // REQUIRED servicePort: <string> // REQUIRED

Determines if the schema is specified in this YAML resource, or if it’s specified in the API Context
from Exchange (Connected Mode only). Supported values: `inline` or `context`. You must specify
`inline` when configuring the policy in Local Mode.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>wsdlUrl</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>URL of where to access the WSDL</p></div></div></td></tr><tr><td><div><div><p><code>encoding</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>UTF-8</p></div></div></td><td><div><div><p>Encoding of the WSDL</p></div></div></td></tr><tr><td><div><div><p><code>serviceName</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>SOAP service name defined in the WSDL that validates requests</p></div></div></td></tr><tr><td><div><div><p><code>servicePort</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>SOAP port name defined in the WSDL that validates requests</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: soap-validation config: wsdlUrl: encoding: UTF-8 serviceName: servicePort:

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Service Name</p></div></div></td><td><div><div><p>SOAP service name defined in the WSDL that validates requests</p></div></div></td></tr><tr><td><div><div><p>Service Port</p></div></div></td><td><div><div><p>SOAP port name defined in the WSDL that validates requests</p></div></div></td></tr></tbody></table>

## See Also

- [XML Threat Protection Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-xml-threat-protection)

<!-- document id=24aeb491a8f5a9bdfb093a65b0f14012f9b5ab30271209cd2b8fd98e71ffc8aa url=/mulesoft/current/en-us/gateway/1.13/policies-included-soap-schema-validation.md -->

---
product: Omni Gateway
version: 1.13
keywords: xml threat protection, api gateway, flex gateway, gateway, policy
---

# SOAP Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>SOAP Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming traffic against a specified WSDL schema</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.10.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/soap-schema-validation-release-notes">SOAP Schema Validation Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>The policy returns a <code>400</code> for a client error or <code>500</code> for a server error. Error messages are defined by SOAP standard responses.</p></td></tr></tbody></table>

## Summary

> [!NOTE] The Schema Validation policy only supports SOAP 1.1 and 1.2 APIs.

Use the SOAP Schema Validation policy to block incoming requests that don’t conform to the the
defined WSDL schema. This policy prevents malformed or malicious SOAP messages from reaching the
backend and enforces contract compliance between clients and services.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: soap-validation config: wsdlUrl: <string> // REQUIRED encoding: <string> //
REQUIRED, default 'UTF-8' serviceName: <string> // REQUIRED servicePort: <string> // REQUIRED

Determines if the schema is specified in this YAML resource, or if it’s specified in the API Context
from Exchange (Connected Mode only). Supported values: `inline` or `context`. You must specify
`inline` when configuring the policy in Local Mode.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>wsdlUrl</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>URL of where to access the WSDL</p></div></div></td></tr><tr><td><div><div><p><code>encoding</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>UTF-8</p></div></div></td><td><div><div><p>Encoding of the WSDL</p></div></div></td></tr><tr><td><div><div><p><code>serviceName</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>SOAP service name defined in the WSDL that validates requests</p></div></div></td></tr><tr><td><div><div><p><code>servicePort</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>SOAP port name defined in the WSDL that validates requests</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: soap-validation config: wsdlUrl: encoding: UTF-8 serviceName: servicePort:

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Service Name</p></div></div></td><td><div><div><p>SOAP service name defined in the WSDL that validates requests</p></div></div></td></tr><tr><td><div><div><p>Service Port</p></div></div></td><td><div><div><p>SOAP port name defined in the WSDL that validates requests</p></div></div></td></tr></tbody></table>

## See Also

- [XML Threat Protection Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-xml-threat-protection)

<!-- document id=23159aec47da1672ae32859a72cf4e2f3725cd48e8af00825d1371dc8033cfed url=/mulesoft/current/en-us/gateway/latest/policies-included-soap-schema-validation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: xml threat protection, api gateway, flex gateway, gateway, policy
---

# SOAP Schema Validation Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>SOAP Schema Validation</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates incoming traffic against a specified WSDL schema</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.10.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/soap-schema-validation-release-notes">SOAP Schema Validation Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>The policy returns a <code>400</code> for a client error or <code>500</code> for a server error. Error messages are defined by SOAP standard responses.</p></td></tr></tbody></table>

## Summary

> [!NOTE] The Schema Validation policy only supports SOAP 1.1 and 1.2 APIs.

Use the SOAP Schema Validation policy to block incoming requests that don’t conform to the the
defined WSDL schema. This policy prevents malformed or malicious SOAP messages from reaching the
backend and enforces contract compliance between clients and services.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: soap-validation config: wsdlUrl: <string> // REQUIRED encoding: <string> //
REQUIRED, default 'UTF-8' serviceName: <string> // REQUIRED servicePort: <string> // REQUIRED

Determines if the schema is specified in this YAML resource, or if it’s specified in the API Context
from Exchange (Connected Mode only). Supported values: `inline` or `context`. You must specify
`inline` when configuring the policy in Local Mode.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>wsdlUrl</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>URL of where to access the WSDL</p></div></div></td></tr><tr><td><div><div><p><code>encoding</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>UTF-8</p></div></div></td><td><div><div><p>Encoding of the WSDL</p></div></div></td></tr><tr><td><div><div><p><code>serviceName</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>SOAP service name defined in the WSDL that validates requests</p></div></div></td></tr><tr><td><div><div><p><code>servicePort</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>SOAP port name defined in the WSDL that validates requests</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: soap-validation config: wsdlUrl: encoding: UTF-8 serviceName: servicePort:

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Service Name</p></div></div></td><td><div><div><p>SOAP service name defined in the WSDL that validates requests</p></div></div></td></tr><tr><td><div><div><p>Service Port</p></div></div></td><td><div><div><p>SOAP port name defined in the WSDL that validates requests</p></div></div></td></tr></tbody></table>

## See Also

- [XML Threat Protection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-xml-threat-protection)

<!-- document id=30031d6c20df038fca00846c5eb6499164a5127d4f1df1c1b03b672a2cac1c98 url=/mulesoft/current/en-us/gateway/1.12/policies-included-spike-control.md -->

---
product: Omni Gateway
version: 1.12
keywords: spike control, api gateway, flex gateway, gateway, policy
---

# Spike Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Spike Control</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Regulates API traffic</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>429 - The number of requests by HTTP APIs exceeded the configured limit. Request rejected after specified number of reattempts.</p></div></div></td></tr></tbody></table>

## Summary

The Spike Control policy regulates your API request traffic by limiting the number of messages
processed by an API. The policy ensures that the number of messages processed within a specified
time does not exceed the limit that you configure. If the number is exceeded, the request is queued
for retry based on you have configured the policy.

## Configuring Policy Parameters

The Spike Control policy does not perform quota enforcement. The configuration parameters are
restricted to protect the API and backend. Therefore, to ensure maximum performance, configure these
parameters to the lowest possible value.

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: spike-control-flex config: maximumRequests: <int> // REQUIRED, default: 1
timePeriodInMilliseconds: <int> // REQUIRED, default: 1000 delayTimeInMillis: <int> // REQUIRED,
default: 1000 delayAttempts: <int> // REQUIRED, default: 1 queuingLimit: <int> // OPTIONAL, default:
0 exposeHeaders: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>Number of allowed requests in the time window</p></div></div></td></tr><tr><td><div><div><p><code>timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>Time window size</p></div></div></td></tr><tr><td><div><div><p><code>delayTimeInMillis</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying, in the event there is no quota remaining</p></div></div></td></tr><tr><td><div><div><p><code>delayAttempts</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td></tr><tr><td><div><div><p><code>queuingLimit</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Enable it only for internal APIs. Allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: spike-control-flex config: queuingLimit: 0 exposeHeaders: true
delayTimeInMillis: 1000 timePeriodInMilliseconds: 1000 delayAttempts: 1 maximumRequests: 100000

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The number of requests allowed (in milliseconds) in the specified window</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The number of milliseconds, within which a request must be processed</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Time in Milliseconds</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying (in milliseconds) in case there is no quota remaining</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Attempts</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Queuing Limit</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Enable it only for internal APIs, allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

To enforce request quotas, see the
[Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting-sla) and
[Rate Limiting Policy](https://docs.mulesoft.com/gateway/1.12/policies-included-rate-limiting).

## How This Policy Works

The Spike Control policy uses a _Sliding Window Algorithm_ which reduces spikes in traffic and
protects the gateway instance. The window self-adjusts its display size to accommodate results over
time.

If the current window has no remaining request quota, without closing the connection to the client,
the Spike Control policy allows requests to be queued for processing later. For your policy to queue
the requests, you must configure the policy parameters, as shown in the following example:

- `Time Period`: 1 second

- `Number of Reqs`: 2

- `Delay Time in Milliseconds`: 499 milliseconds

- `Delay Attempts`: 1

- `Queuing Limit`: 5

Queuing a request requires retaining a thread and an HTTP connection. When you specify a
`Queuing Limit` for the policy, the parameter protects the gateway from running out of resources and
ensures that the API does not fail in case of an attack.

## Request Timelines

The following diagram illustrates the lifespan of each request accepted by the algorithm, using the
configuration defined in the previous section:

![A timeline that shows accepted, rejected, and queued requests](/mulesoft/current/en-us/gateway/1.12/_images/spike-control.png)

1.  The first two requests are accepted and the available quota is now 0.

    The quota increases to 1 after one second (the `window size` value) passes from request #1.

2.  Request #3 arrives.

    Because no quota is available, the request is queued for 499 milliseconds.

3.  Request #4 arrives.

    Because there still is no quota available, the request is queued for 499 milliseconds.

4.  Shortly before request #3 is retried, request #1 ages a second and its quota is released because
    it falls out of the window.

5.  Quota is now 1, and request #3 is reprocessed successfully.

    Quota returns to 0 until request #2 ages 1 second.

6.  Request #4 delay concludes and it must be reprocessed.

    Request #4 is rejected. Requests #2 and #3 have not aged a second yet and there is no quota
    available. Request #4 have no more delays.

7.  Request #5 arrives.

    Because request #2 has already aged more than a second, the request is accepted.

This example illustrates request delays and how queuing regulates spikes in traffic. In
high-contention scenarios, the backend continues to function properly (it serves no more than X
requests in the last Y milliseconds).

Users querying the API might still see their requests being served, but with higher latency. The
exact configuration for the policy depends exclusively on your API and its throughput.

## FAQ

**When does the sliding window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

The algorithm uses a sliding window that monitors transactions for the amount of time that you
configure in the policy.

**What happens when the quota is exhausted?**

When the request quota is exhausted, the Spike Control policy queues the request and retries as
configured. The request is rejected if no quota is remaining after several retries. Quota for other
requests is available only after the first request exceeds the time limit configured in the policy;
in this way, requests are processed in cycles.

**Can I configure multiple windows?**

No. The Spike Control policy ensures that the backend server does not serve more requests than it
can handle. If you need accountability, use either Rate-Limiting SLA or Rate Limit policies instead.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of quota currently available

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until the oldest request ages enough to
  fall outside of the sliding window.

  If quota is still available, the header is set to 0 (zero) because the algorithm can still serve
  new requests.

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=1c605e68b6dd919e198988ab21b9e8a79d8f2cc26f6fa92c004b1a0b2bf3aea6 url=/mulesoft/current/en-us/gateway/1.13/policies-included-spike-control.md -->

---
product: Omni Gateway
version: 1.13
keywords: spike control, api gateway, flex gateway, gateway, policy
---

# Spike Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Spike Control</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Regulates API traffic</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/spike-control-release-notes">Spike Control</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>429 - The number of requests by HTTP APIs exceeded the configured limit. Request rejected after specified number of reattempts.</p></div></div></td></tr></tbody></table>

## Summary

The Spike Control policy regulates your API request traffic by limiting the number of messages
processed by an API. The policy ensures that the number of messages processed within a specified
time does not exceed the limit that you configure. If the number is exceeded, the request is queued
for retry based on you have configured the policy.

## Configuring Policy Parameters

The Spike Control policy does not perform quota enforcement. The configuration parameters are
restricted to protect the API and backend. Therefore, to ensure maximum performance, configure these
parameters to the lowest possible value.

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: spike-control-flex config: maximumRequests: <int> // REQUIRED, default: 1
timePeriodInMilliseconds: <int> // REQUIRED, default: 1000 delayTimeInMillis: <int> // REQUIRED,
default: 1000 delayAttempts: <int> // REQUIRED, default: 1 queuingLimit: <int> // OPTIONAL, default:
0 exposeHeaders: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>Number of allowed requests in the time window</p></div></div></td></tr><tr><td><div><div><p><code>timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>Time window size</p></div></div></td></tr><tr><td><div><div><p><code>delayTimeInMillis</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying, in the event there is no quota remaining</p></div></div></td></tr><tr><td><div><div><p><code>delayAttempts</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td></tr><tr><td><div><div><p><code>queuingLimit</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Enable it only for internal APIs. Allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: spike-control-flex config: queuingLimit: 0 exposeHeaders: true
delayTimeInMillis: 1000 timePeriodInMilliseconds: 1000 delayAttempts: 1 maximumRequests: 100000

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The number of requests allowed (in milliseconds) in the specified window</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The number of milliseconds, within which a request must be processed</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Time in Milliseconds</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying (in milliseconds) in case there is no quota remaining</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Attempts</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Queuing Limit</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Enable it only for internal APIs, allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

To enforce request quotas, see the
[Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting-sla) and
[Rate Limiting Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-rate-limiting).

## How This Policy Works

The Spike Control policy uses a _Sliding Window Algorithm_ which reduces spikes in traffic and
protects the gateway instance. The window self-adjusts its display size to accommodate results over
time.

If the current window has no remaining request quota, without closing the connection to the client,
the Spike Control policy allows requests to be queued for processing later. For your policy to queue
the requests, you must configure the policy parameters, as shown in the following example:

- `Time Period`: 1 second

- `Number of Reqs`: 2

- `Delay Time in Milliseconds`: 499 milliseconds

- `Delay Attempts`: 1

- `Queuing Limit`: 5

Queuing a request requires retaining a thread and an HTTP connection. When you specify a
`Queuing Limit` for the policy, the parameter protects the gateway from running out of resources and
ensures that the API does not fail in case of an attack.

## Request Timelines

The following diagram illustrates the lifespan of each request accepted by the algorithm, using the
configuration defined in the previous section:

![A timeline that shows accepted, rejected, and queued requests](/mulesoft/current/en-us/gateway/1.13/_images/spike-control.png)

1.  The first two requests are accepted and the available quota is now 0.

    The quota increases to 1 after one second (the `window size` value) passes from request #1.

2.  Request #3 arrives.

    Because no quota is available, the request is queued for 499 milliseconds.

3.  Request #4 arrives.

    Because there still is no quota available, the request is queued for 499 milliseconds.

4.  Shortly before request #3 is retried, request #1 ages a second and its quota is released because
    it falls out of the window.

5.  Quota is now 1, and request #3 is reprocessed successfully.

    Quota returns to 0 until request #2 ages 1 second.

6.  Request #4 delay concludes and it must be reprocessed.

    Request #4 is rejected. Requests #2 and #3 have not aged a second yet and there is no quota
    available. Request #4 have no more delays.

7.  Request #5 arrives.

    Because request #2 has already aged more than a second, the request is accepted.

This example illustrates request delays and how queuing regulates spikes in traffic. In
high-contention scenarios, the backend continues to function properly (it serves no more than X
requests in the last Y milliseconds).

Users querying the API might still see their requests being served, but with higher latency. The
exact configuration for the policy depends exclusively on your API and its throughput.

## FAQ

**When does the sliding window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

The algorithm uses a sliding window that monitors transactions for the amount of time that you
configure in the policy.

**What happens when the quota is exhausted?**

When the request quota is exhausted, the Spike Control policy queues the request and retries as
configured. The request is rejected if no quota is remaining after several retries. Quota for other
requests is available only after the first request exceeds the time limit configured in the policy;
in this way, requests are processed in cycles.

**Can I configure multiple windows?**

No. The Spike Control policy ensures that the backend server does not serve more requests than it
can handle. If you need accountability, use either Rate-Limiting SLA or Rate Limit policies instead.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of quota currently available

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until the oldest request ages enough to
  fall outside of the sliding window.

  If quota is still available, the header is set to 0 (zero) because the algorithm can still serve
  new requests.

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=664c7f6ddfad5c8fccd5130369110cfe661fb65334383921867afca630cce71c url=/mulesoft/current/en-us/gateway/1.9/policies-included-spike-control.md -->

---
product: Omni Gateway
version: 1.9
keywords: spike control, api gateway, flex gateway, gateway, policy
---

# Spike Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Spike Control</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Regulates API traffic</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>429 - The number of requests by HTTP APIs exceeded the configured limit. Request rejected after specified number of reattempts.</p></div></div></td></tr></tbody></table>

## Summary

The Spike Control policy regulates your API request traffic by limiting the number of messages
processed by an API. The policy ensures that the number of messages processed within a specified
time does not exceed the limit that you configure. If the number is exceeded, the request is queued
for retry based on you have configured the policy.

## Configuring Policy Parameters

The Spike Control policy does not perform quota enforcement. The configuration parameters are
restricted to protect the API and backend. Therefore, to ensure maximum performance, configure these
parameters to the lowest possible value.

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: spike-control-flex config: maximumRequests: <int> // REQUIRED, default: 1
timePeriodInMilliseconds: <int> // REQUIRED, default: 1000 delayTimeInMillis: <int> // REQUIRED,
default: 1000 delayAttempts: <int> // REQUIRED, default: 1 queuingLimit: <int> // OPTIONAL, default:
0 exposeHeaders: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>Number of allowed requests in the time window</p></div></div></td></tr><tr><td><div><div><p><code>timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>Time window size</p></div></div></td></tr><tr><td><div><div><p><code>delayTimeInMillis</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying, in the event there is no quota remaining</p></div></div></td></tr><tr><td><div><div><p><code>delayAttempts</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td></tr><tr><td><div><div><p><code>queuingLimit</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Enable it only for internal APIs. Allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: spike-control-flex config: queuingLimit: 0 exposeHeaders: true
delayTimeInMillis: 1000 timePeriodInMilliseconds: 1000 delayAttempts: 1 maximumRequests: 100000

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The number of requests allowed (in milliseconds) in the specified window</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The number of milliseconds, within which a request must be processed</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Time in Milliseconds</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying (in milliseconds) in case there is no quota remaining</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Attempts</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Queuing Limit</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Enable it only for internal APIs, allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

To enforce request quotas, see the
[Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting-sla) and
[Rate Limiting Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-rate-limiting).

## How This Policy Works

The Spike Control policy uses a _Sliding Window Algorithm_ which reduces spikes in traffic and
protects the gateway instance. The window self-adjusts its display size to accommodate results over
time.

If the current window has no remaining request quota, without closing the connection to the client,
the Spike Control policy allows requests to be queued for processing later. For your policy to queue
the requests, you must configure the policy parameters, as shown in the following example:

- `Time Period`: 1 second

- `Number of Reqs`: 2

- `Delay Time in Milliseconds`: 499 milliseconds

- `Delay Attempts`: 1

- `Queuing Limit`: 5

Queuing a request requires retaining a thread and an HTTP connection. When you specify a
`Queuing Limit` for the policy, the parameter protects the gateway from running out of resources and
ensures that the API does not fail in case of an attack.

## Request Timelines

The following diagram illustrates the lifespan of each request accepted by the algorithm, using the
configuration defined in the previous section:

![A timeline that shows accepted, rejected, and queued requests](/mulesoft/current/en-us/gateway/1.9/_images/spike-control.png)

1.  The first two requests are accepted and the available quota is now 0.

    The quota increases to 1 after one second (the `window size` value) passes from request #1.

2.  Request #3 arrives.

    Because no quota is available, the request is queued for 499 milliseconds.

3.  Request #4 arrives.

    Because there still is no quota available, the request is queued for 499 milliseconds.

4.  Shortly before request #3 is retried, request #1 ages a second and its quota is released because
    it falls out of the window.

5.  Quota is now 1, and request #3 is reprocessed successfully.

    Quota returns to 0 until request #2 ages 1 second.

6.  Request #4 delay concludes and it must be reprocessed.

    Request #4 is rejected. Requests #2 and #3 have not aged a second yet and there is no quota
    available. Request #4 have no more delays.

7.  Request #5 arrives.

    Because request #2 has already aged more than a second, the request is accepted.

This example illustrates request delays and how queuing regulates spikes in traffic. In
high-contention scenarios, the backend continues to function properly (it serves no more than X
requests in the last Y milliseconds).

Users querying the API might still see their requests being served, but with higher latency. The
exact configuration for the policy depends exclusively on your API and its throughput.

## FAQ

**When does the sliding window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

The algorithm uses a sliding window that monitors transactions for the amount of time that you
configure in the policy.

**What happens when the quota is exhausted?**

When the request quota is exhausted, the Spike Control policy queues the request and retries as
configured. The request is rejected if no quota is remaining after several retries. Quota for other
requests is available only after the first request exceeds the time limit configured in the policy;
in this way, requests are processed in cycles.

**Can I configure multiple windows?**

No. The Spike Control policy ensures that the backend server does not serve more requests than it
can handle. If you need accountability, use either Rate-Limiting SLA or Rate Limit policies instead.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of quota currently available

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until the oldest request ages enough to
  fall outside of the sliding window.

  If quota is still available, the header is set to 0 (zero) because the algorithm can still serve
  new requests.

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=4846d553df59c4d0fe737dc5daf956cbcd1ce8bf51bc9bef8f87cf02d234b131 url=/mulesoft/current/en-us/gateway/latest/policies-included-spike-control.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: spike control, api gateway, flex gateway, gateway, policy
---

# Spike Control Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Spike Control</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Regulates API traffic</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/spike-control-release-notes">Spike Control</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div></div></td></tr><tr><td><div><div><p>429 - The number of requests by HTTP APIs exceeded the configured limit. Request rejected after specified number of reattempts.</p></div></div></td></tr></tbody></table>

## Summary

The Spike Control policy regulates your API request traffic by limiting the number of messages
processed by an API. The policy ensures that the number of messages processed within a specified
time does not exceed the limit that you configure. If the number is exceeded, the request is queued
for retry based on you have configured the policy.

## Configuring Policy Parameters

The Spike Control policy does not perform quota enforcement. The configuration parameters are
restricted to protect the API and backend. Therefore, to ensure maximum performance, configure these
parameters to the lowest possible value.

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: spike-control-flex config: maximumRequests: <int> // REQUIRED, default: 1
timePeriodInMilliseconds: <int> // REQUIRED, default: 1000 delayTimeInMillis: <int> // REQUIRED,
default: 1000 delayAttempts: <int> // REQUIRED, default: 1 queuingLimit: <int> // OPTIONAL, default:
0 exposeHeaders: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>Number of allowed requests in the time window</p></div></div></td></tr><tr><td><div><div><p><code>timePeriodInMilliseconds</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>Time window size</p></div></div></td></tr><tr><td><div><div><p><code>delayTimeInMillis</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1000</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying, in the event there is no quota remaining</p></div></div></td></tr><tr><td><div><div><p><code>delayAttempts</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>1</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td></tr><tr><td><div><div><p><code>queuingLimit</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>0</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td></tr><tr><td><div><div><p><code>exposeHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Enable it only for internal APIs. Allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: spike-control-flex config: queuingLimit: 0 exposeHeaders: true
delayTimeInMillis: 1000 timePeriodInMilliseconds: 1000 delayAttempts: 1 maximumRequests: 100000

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Number of Reqs</p></div></div></td><td><div><div><p>The number of requests allowed (in milliseconds) in the specified window</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Time Period</p></div></div></td><td><div><div><p>The number of milliseconds, within which a request must be processed</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Time in Milliseconds</p></div></div></td><td><div><div><p>The amount of time for which each request is retained before retrying (in milliseconds) in case there is no quota remaining</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Delay Attempts</p></div></div></td><td><div><div><p>The number of times a request is retried before it is rejected</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Queuing Limit</p></div></div></td><td><div><div><p>The number of requests that can be queued at the any given time</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Expose Headers</p></div></div></td><td><div><div><p>Enable it only for internal APIs, allows the policy to return information about the algorithm behavior in the X-RateLimit headers</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Method &amp; Resource conditions</p></div></div></td><td><div><div><p>The option to add configurations to only a select few or all methods and resources of the API</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

To enforce request quotas, see the
[Rate Limiting: SLA-Based Policy](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting-sla) and
[Rate Limiting Policy](https://docs.mulesoft.com/gateway/latest/policies-included-rate-limiting).

## How This Policy Works

The Spike Control policy uses a _Sliding Window Algorithm_ which reduces spikes in traffic and
protects the gateway instance. The window self-adjusts its display size to accommodate results over
time.

If the current window has no remaining request quota, without closing the connection to the client,
the Spike Control policy allows requests to be queued for processing later. For your policy to queue
the requests, you must configure the policy parameters, as shown in the following example:

- `Time Period`: 1 second

- `Number of Reqs`: 2

- `Delay Time in Milliseconds`: 499 milliseconds

- `Delay Attempts`: 1

- `Queuing Limit`: 5

Queuing a request requires retaining a thread and an HTTP connection. When you specify a
`Queuing Limit` for the policy, the parameter protects the gateway from running out of resources and
ensures that the API does not fail in case of an attack.

## Request Timelines

The following diagram illustrates the lifespan of each request accepted by the algorithm, using the
configuration defined in the previous section:

![A timeline that shows accepted, rejected, and queued requests](/mulesoft/current/en-us/gateway/latest/_images/spike-control.png)

1.  The first two requests are accepted and the available quota is now 0.

    The quota increases to 1 after one second (the `window size` value) passes from request #1.

2.  Request #3 arrives.

    Because no quota is available, the request is queued for 499 milliseconds.

3.  Request #4 arrives.

    Because there still is no quota available, the request is queued for 499 milliseconds.

4.  Shortly before request #3 is retried, request #1 ages a second and its quota is released because
    it falls out of the window.

5.  Quota is now 1, and request #3 is reprocessed successfully.

    Quota returns to 0 until request #2 ages 1 second.

6.  Request #4 delay concludes and it must be reprocessed.

    Request #4 is rejected. Requests #2 and #3 have not aged a second yet and there is no quota
    available. Request #4 have no more delays.

7.  Request #5 arrives.

    Because request #2 has already aged more than a second, the request is accepted.

This example illustrates request delays and how queuing regulates spikes in traffic. In
high-contention scenarios, the backend continues to function properly (it serves no more than X
requests in the last Y milliseconds).

Users querying the API might still see their requests being served, but with higher latency. The
exact configuration for the policy depends exclusively on your API and its throughput.

## FAQ

**When does the sliding window start?**

The window starts with the first request after the policy is successfully applied.

**What type of window does the algorithm use?**

The algorithm uses a sliding window that monitors transactions for the amount of time that you
configure in the policy.

**What happens when the quota is exhausted?**

When the request quota is exhausted, the Spike Control policy queues the request and retries as
configured. The request is rejected if no quota is remaining after several retries. Quota for other
requests is available only after the first request exceeds the time limit configured in the policy;
in this way, requests are processed in cycles.

**Can I configure multiple windows?**

No. The Spike Control policy ensures that the backend server does not serve more requests than it
can handle. If you need accountability, use either Rate-Limiting SLA or Rate Limit policies instead.

**What does each response header mean?**

Each response header has information about the current state of the request:

- X-Ratelimit-Remaining: The amount of quota currently available

- X-Ratelimit-Limit: The maximum available requests per window

- X-Ratelimit-Reset: The remaining time, in milliseconds, until the oldest request ages enough to
  fall outside of the sliding window.

  If quota is still available, the header is set to 0 (zero) because the algorithm can still serve
  new requests.

By default, the X-RateLimit headers are disabled in the response. You can enable these headers by
selecting **Expose Headers** when you configure the policy.

**When should I use Rate Limiting instead of Rate Limiting SLA or Spike Control?**

Use Rate Limiting and Rate-Limiting SLA policies for accountability and to enforce a hard limit to a
group (using the identifier in Rate Limiting) or to a client application (using Rate Limiting-SLA).
If you want to protect your backend, use the Spike Control policy instead.

<!-- document id=b35f5476680c9c14f60358a80e4a875b9ffe009537f4b98352f171086850c76c url=/mulesoft/current/en-us/gateway/1.12/policies-included-sse-logging.md -->

# SSE Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs every SSE event while streaming</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Flex Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.9.3</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The SSE Logging policy enables logging for SSE connections. The configured SSE logs appear in Flex Gateway logs.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">This policy only provides logs for SSE events. To log non-SSE information, see <a href="https://docs.mulesoft.com/gateway/1.12/policies-included-message-logging" class="xref page">Message Logging Policy</a>.</td></tr></tbody></table>

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#flex-gateway-local-mode)Flex Gateway Local Mode

The SSE Logging policy isn’t supported in Local Mode.

### [](#connected-mode)Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Element</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Logs</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of logs executed on every SSE event.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression for SSE response messages</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave Expression that extracts information from the SSE Event. Use <code><mark>[payload]</mark></code> for the event’s payload, <code>[vars.data]</code> for the event data, and <code>#[vars.id]</code> for the event ID.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>String prefix to add to each log message.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Level</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code>.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=80e46e2611f5b96163b62be74f3cc50a580ab1de9e65358924a57b6dc8c3aa8c url=/mulesoft/current/en-us/gateway/1.13/policies-included-sse-logging.md -->

# SSE Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs every SSE event while streaming</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.9.3</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/sse-logging-release-notes" class="xref page">Server-Sent Events (SSE) Logging</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The SSE Logging policy enables logging for SSE connections. The configured SSE logs appear in Omni Gateway logs.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">This policy only provides logs for SSE events. To log non-SSE information, see <a href="https://docs.mulesoft.com/gateway/1.13/policies-included-message-logging" class="xref page">Message Logging Policy</a>.</td></tr></tbody></table>

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#omni-gateway-local-mode)Omni Gateway Local Mode

The SSE Logging policy isn’t supported in Local Mode.

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Element</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Logs</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of logs executed on every SSE event.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression for SSE response messages</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave Expression that extracts information from the SSE Event. Use <code><mark>[payload]</mark></code> for the event’s payload, <code>[vars.data]</code> for the event data, and <code>#[vars.id]</code> for the event ID.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>String prefix to add to each log message.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Level</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code>.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=ddcc71587b05a40b74753dd9ac470b84e19b8ab977177cc76a857b84302ab213 url=/mulesoft/current/en-us/gateway/1.9/policies-included-sse-logging.md -->

# SSE Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs every SSE event while streaming</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Flex Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.9.3</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The SSE Logging policy enables logging for SSE connections. The configured SSE logs appear in Flex Gateway logs.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">This policy only provides logs for SSE events. To log non-SSE information, see <a href="https://docs.mulesoft.com/gateway/1.9/policies-included-message-logging" class="xref page">Message Logging Policy</a>.</td></tr></tbody></table>

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#flex-gateway-local-mode)Flex Gateway Local Mode

The SSE Logging policy isn’t supported in Local Mode.

### [](#connected-mode)Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Element</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Logs</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of logs executed on every SSE event.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression for SSE response messages</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave Expression that extracts information from the SSE Event. Use <code><mark>[payload]</mark></code> for the event’s payload, <code>[vars.data]</code> for the event data, and <code>#[vars.id]</code> for the event ID.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>String prefix to add to each log message.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Level</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code>.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=c0a337c7817011b2d75cae6b7893254d17067e839913b24c07b052acde721c51 url=/mulesoft/current/en-us/gateway/latest/policies-included-sse-logging.md -->

# SSE Logging Policy

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Policy Name</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Summary</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logs every SSE event while streaming</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Category</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSE</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>First Omni Gateway version available</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">v1.9.3</p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Release Notes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://docs.mulesoft.com/release-notes/gateway/policies/sse-logging-release-notes" class="xref page">Server-Sent Events (SSE) Logging</a></p></td>
</tr>
<tr>
<td class="tableblock halign-right valign-top"><p class="tableblock"><strong>Returned Status Codes</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">No return codes exist for this policy.</p></td>
</tr>
</tbody>
</table>

## [](#summary)Summary

The SSE Logging policy enables logging for SSE connections. The configured SSE logs appear in Omni Gateway logs.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">This policy only provides logs for SSE events. To log non-SSE information, see <a href="https://docs.mulesoft.com/gateway/latest/policies-included-message-logging" class="xref page">Message Logging Policy</a>.</td></tr></tbody></table>

## [](#configuring-policy-parameters)Configuring Policy Parameters

### [](#omni-gateway-local-mode)Omni Gateway Local Mode

The SSE Logging policy isn’t supported in Local Mode.

### [](#connected-mode)Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table class="tableblock frame-all grid-all fit-content spread">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Element</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Logs</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>List of logs executed on every SSE event.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave expression for SSE response messages</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DataWeave Expression that extracts information from the SSE Event. Use <code><mark>[payload]</mark></code> for the event’s payload, <code>[vars.data]</code> for the event data, and <code>#[vars.id]</code> for the event ID.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Category</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>String prefix to add to each log message.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Level</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Defines the level of message to log: <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or <code>DEBUG</code>.<br>
For more information, see <a href="#severity-levels">Message Logging Severity Levels</a>.</p>
</div></div></td>
</tr>
</tbody>
</table>

## [](#severity-levels)Message Logging Severity Levels

When you configure a Message Logging policy for your API instance, you can assign a severity level. Each severity level includes a specific set of information in the log report.

Log reports include the severity level you select and the following levels on the hierarchy.

For example, if you select DEBUG, the log reports include the DEBUG severity level as well as the INFO, WARN, and ERROR severity levels. However, if you select ERROR, the log reports include only error messages. The following table describes the type of information included in the logs for each severity level:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Log Severity Level</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>DEBUG</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Tracing information used by application developers.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>INFO</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Informational messages that highlight the progress of the application.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>WARN</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Potentially harmful situations that indicate potential problems.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>ERROR</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Events that prevent normal program execution but might allow the application to continue running.</p>
</div></div></td>
</tr>
</tbody>
</table>

<!-- document id=1159b731cde2802823fb02cdd09180f584cf09a029f09d6c00577f9b99fbfcc8 url=/mulesoft/current/en-us/gateway/1.12/policies-included-stream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.12
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Stream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration a stream can remain idle without receiving a request or response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Stream timeout</p></td></tr></tbody></table>

## Summary

The Stream Idle Timeout policy sets a maximum duration for which a stream can remain idle without
receiving any data, either inbound from the client to Flex Gateway or outbound from Flex Gateway to
the upstream service. The policy prevents idle connections from consuming resources unnecessarily.
The timeout period starts at the last activity on the stream, whether the activity is a request or a
response.

By default, all Flex Gateway API instances have a stream timeout of 300 seconds. Apply the policy to
override the default timeout.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: stream-idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>300</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: stream-idle-timeout-flex config: timeout: 3

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Stream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=701d33aa4cb2fcde790215a92f7f97c5cf8ad7244b930e85101bf82f5a0254b0 url=/mulesoft/current/en-us/gateway/1.13/policies-included-stream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.13
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Stream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration a stream can remain idle without receiving a request or response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/stream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Stream timeout</p></td></tr></tbody></table>

## Summary

The Stream Idle Timeout policy sets a maximum duration for which a stream can remain idle without
receiving any data, either inbound from the client to Omni Gateway or outbound from Omni Gateway to
the upstream service. The policy prevents idle connections from consuming resources unnecessarily.
The timeout period starts at the last activity on the stream, whether the activity is a request or a
response.

By default, all Omni Gateway API instances have a stream timeout of 300 seconds. Apply the policy to
override the default timeout.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: stream-idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>300</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: stream-idle-timeout-flex config: timeout: 3

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Stream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=f5285c077b3a1b7cc4e122d96d67b7b59b6aecdb05933511f52810afb64a145a url=/mulesoft/current/en-us/gateway/1.9/policies-included-stream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.9
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Stream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration a stream can remain idle without receiving a request or response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Stream timeout</p></td></tr></tbody></table>

## Summary

The Stream Idle Timeout policy sets a maximum duration for which a stream can remain idle without
receiving any data, either inbound from the client to Flex Gateway or outbound from Flex Gateway to
the upstream service. The policy prevents idle connections from consuming resources unnecessarily.
The timeout period starts at the last activity on the stream, whether the activity is a request or a
response.

By default, all Flex Gateway API instances have a stream timeout of 300 seconds. Apply the policy to
override the default timeout.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: stream-idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>300</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: stream-idle-timeout-flex config: timeout: 3

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Stream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=1d40d178028535ecdcce6c9683d5a6c14e8e0c5879405cf5f5d7961ba713fdbb url=/mulesoft/current/en-us/gateway/latest/policies-included-stream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Stream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum duration a stream can remain idle without receiving a request or response</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/stream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Stream timeout</p></td></tr></tbody></table>

## Summary

The Stream Idle Timeout policy sets a maximum duration for which a stream can remain idle without
receiving any data, either inbound from the client to Omni Gateway or outbound from Omni Gateway to
the upstream service. The policy prevents idle connections from consuming resources unnecessarily.
The timeout period starts at the last activity on the stream, whether the activity is a request or a
response.

By default, all Omni Gateway API instances have a stream timeout of 300 seconds. Apply the policy to
override the default timeout.

This policy overrides every other Stream Idle Timeout configuration for the API instance you apply
it to, whether the policy value is higher or lower. To change the gateway-level timeout, see
[Configure Timeouts for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-timeout) or
[Configuring Timeouts in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-timeout).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: stream-idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>300</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: stream-idle-timeout-flex config: timeout: 3

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Stream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=c5263224b67990a5d977561b3edce97d9349f0545db459e109b4d73124b03406 url=/mulesoft/current/en-us/gateway/1.12/policies-included-tracing.md -->

---
product: Omni Gateway
version: 1.12
keywords: api gateway, flex gateway, gateway, policy, otel, otel support, OpenTelemetry, distributed tracing
---

# Tracing Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Tracing</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Override global tracing configuration</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Troubleshooting</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>1.10.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The Tracing policy enables you to override the global distributed tracing parameters for an API.

## Before You Begin

Distributed tracing is disabled by default. After you have enabled distributed tracing with a Flex
Gateway global configuration, you can use this policy to override the global distributed tracing
parameters for an API.

For details on how to enable distributed tracing, see:

- [Configuring Flex Gateway Distributed Tracing in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tracing-config)

- [Configuring Flex Gateway Distributed Tracing in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tracing-config)

- [Configuring Distributed Tracing for Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-managed-tracing-config)

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: tracing-flex config: sampling: client: number // REQUIRED random: number //
REQUIRED overall: number // REQUIRED spanName: <string> // OPTIONAL labels: <array> // OPTIONAL,
default: \[\] - name: <string> // REQUIRED type: <string> // REQUIRED keyName: <string> // REQUIRED
defaultValue: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>sampling.client</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are force traced if the <code>x-client-trace-id</code> header is set.</p></div></div></td></tr><tr><td><div><div><p><code>sampling.random</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.</p></div></div></td></tr><tr><td><div><div><p><code>sampling.overall</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.</p></div></div></td></tr><tr><td><div><div><p><code>spanName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The name of the span. If no span name is configured, the API name is used.</p></div></div></td></tr><tr><td><div><div><p><code>labels</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Array of labels that are added to the trace to be used as span attributes in the trace data.</p></div></div></td></tr><tr><td><div><div><p><code>labels.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The name of the label, used as a span attribute name.</p></div></div></td></tr><tr><td><div><div><p><code>labels.type</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The type of the label specifies where the value for the label is taken from. Supported values are <code>literal</code>, <code>environment</code>, and <code>requestHeader</code>.</p></div></div></td></tr><tr><td><div><div><p><code>labels.keyName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The key name of the label.</p></div></div></td></tr><tr><td><div><div><p><code>labels.defaultValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The default value of the label.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: tracing-flex config: sampling: client: 100 random: 100 overall: 100 spanName:
flightsAPI labels: - name: c-env-tag type: environment keyName: FLEX\_NAME defaultValue:
DEFAULT\_VAL - name: c-header-tag type: requestHeader keyName: :method defaultValue:
DEFAULT\_METHOD - name: c-literal-tag type: literal defaultValue: the-tag

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Client Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are force traced if the <code>x-client-trace-id</code> header is set.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Random Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Overall Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Span name</p></div></div></td><td><div><div><p>The name of the span. If no span name is configured, the API name is used.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Labels</p></div></div></td><td><div><div><p>Array of labels that are added to the trace to be used as span attributes in the trace data.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Label Name</p></div></div></td><td><div><div><p>The name of the label, used as a span attribute name.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Type</p></div></div></td><td><div><div><p>The type of the label specifies where the value for the label is taken from. Supported values are <code>literal</code>, <code>environment</code>, and <code>requestHeader</code>.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Key Name</p></div></div></td><td><div><div><p>The key used to retrieve the value, such as an environment variable or request header name.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Default Value</p></div></div></td><td><div><div><p>Default value to use if the key is not found or the retrieved value is empty.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=06651d5553ff85a904cb6d8bcd797e121a64c108b17cf59aa9dcbe5622b36860 url=/mulesoft/current/en-us/gateway/1.13/policies-included-tracing.md -->

---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, otel, otel support, OpenTelemetry, distributed tracing
---

# Tracing Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Tracing</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Override global tracing configuration</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Troubleshooting</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>1.10.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tracing-release-notes">Tracing</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The Tracing policy enables you to override the global distributed tracing parameters for an API.

## Before You Begin

Distributed tracing is disabled by default. After you have enabled distributed tracing with an Omni
Gateway global configuration, you can use this policy to override the global distributed tracing
parameters for an API.

For details on how to enable distributed tracing, see:

- [Configuring Omni Gateway Distributed Tracing in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tracing-config)

- [Configuring Omni Gateway Distributed Tracing in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tracing-config)

- [Configuring Distributed Tracing for Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/managed-tracing-config)

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: tracing-flex config: sampling: client: number // REQUIRED random: number //
REQUIRED overall: number // REQUIRED spanName: <string> // OPTIONAL labels: <array> // OPTIONAL,
default: \[\] - name: <string> // REQUIRED type: <string> // REQUIRED keyName: <string> // REQUIRED
defaultValue: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>sampling.client</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are force traced if the <code>x-client-trace-id</code> header is set.</p></div></div></td></tr><tr><td><div><div><p><code>sampling.random</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.</p></div></div></td></tr><tr><td><div><div><p><code>sampling.overall</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.</p></div></div></td></tr><tr><td><div><div><p><code>spanName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The name of the span. If no span name is configured, the API name is used.</p></div></div></td></tr><tr><td><div><div><p><code>labels</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Array of labels that are added to the trace to be used as span attributes in the trace data.</p></div></div></td></tr><tr><td><div><div><p><code>labels.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The name of the label, used as a span attribute name.</p></div></div></td></tr><tr><td><div><div><p><code>labels.type</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The type of the label specifies where the value for the label is taken from. Supported values are <code>literal</code>, <code>environment</code>, and <code>requestHeader</code>.</p></div></div></td></tr><tr><td><div><div><p><code>labels.keyName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The key name of the label.</p></div></div></td></tr><tr><td><div><div><p><code>labels.defaultValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The default value of the label.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: tracing-flex config: sampling: client: 100 random: 100 overall: 100 spanName:
flightsAPI labels: - name: c-env-tag type: environment keyName: FLEX\_NAME defaultValue:
DEFAULT\_VAL - name: c-header-tag type: requestHeader keyName: :method defaultValue:
DEFAULT\_METHOD - name: c-literal-tag type: literal defaultValue: the-tag

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Client Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are force traced if the <code>x-client-trace-id</code> header is set.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Random Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Overall Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Span name</p></div></div></td><td><div><div><p>The name of the span. If no span name is configured, the API name is used.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Labels</p></div></div></td><td><div><div><p>Array of labels that are added to the trace to be used as span attributes in the trace data.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Label Name</p></div></div></td><td><div><div><p>The name of the label, used as a span attribute name.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Type</p></div></div></td><td><div><div><p>The type of the label specifies where the value for the label is taken from. Supported values are <code>literal</code>, <code>environment</code>, and <code>requestHeader</code>.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Key Name</p></div></div></td><td><div><div><p>The key used to retrieve the value, such as an environment variable or request header name.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Default Value</p></div></div></td><td><div><div><p>Default value to use if the key is not found or the retrieved value is empty.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=31222f83cd4466165149a3ef523d89f7feb943cc4e5857c83e64c3421dbfc90f url=/mulesoft/current/en-us/gateway/latest/policies-included-tracing.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, otel, otel support, OpenTelemetry, distributed tracing
---

# Tracing Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Tracing</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Override global tracing configuration</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Troubleshooting</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>1.10.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tracing-release-notes">Tracing</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The Tracing policy enables you to override the global distributed tracing parameters for an API.

## Before You Begin

Distributed tracing is disabled by default. After you have enabled distributed tracing with an Omni
Gateway global configuration, you can use this policy to override the global distributed tracing
parameters for an API.

For details on how to enable distributed tracing, see:

- [Configuring Omni Gateway Distributed Tracing in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tracing-config)

- [Configuring Omni Gateway Distributed Tracing in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tracing-config)

- [Configuring Distributed Tracing for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-tracing-config)

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: tracing-flex config: sampling: client: number // REQUIRED random: number //
REQUIRED overall: number // REQUIRED spanName: <string> // OPTIONAL labels: <array> // OPTIONAL,
default: \[\] - name: <string> // REQUIRED type: <string> // REQUIRED keyName: <string> // REQUIRED
defaultValue: <string> // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>sampling.client</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are force traced if the <code>x-client-trace-id</code> header is set.</p></div></div></td></tr><tr><td><div><div><p><code>sampling.random</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.</p></div></div></td></tr><tr><td><div><div><p><code>sampling.overall</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>100</p></div></div></td><td><div><div><p>The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.</p></div></div></td></tr><tr><td><div><div><p><code>spanName</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The name of the span. If no span name is configured, the API name is used.</p></div></div></td></tr><tr><td><div><div><p><code>labels</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Array of labels that are added to the trace to be used as span attributes in the trace data.</p></div></div></td></tr><tr><td><div><div><p><code>labels.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The name of the label, used as a span attribute name.</p></div></div></td></tr><tr><td><div><div><p><code>labels.type</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The type of the label specifies where the value for the label is taken from. Supported values are <code>literal</code>, <code>environment</code>, and <code>requestHeader</code>.</p></div></div></td></tr><tr><td><div><div><p><code>labels.keyName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The key name of the label.</p></div></div></td></tr><tr><td><div><div><p><code>labels.defaultValue</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The default value of the label.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: tracing-flex config: sampling: client: 100 random: 100 overall: 100 spanName:
flightsAPI labels: - name: c-env-tag type: environment keyName: FLEX\_NAME defaultValue:
DEFAULT\_VAL - name: c-header-tag type: requestHeader keyName: :method defaultValue:
DEFAULT\_METHOD - name: c-literal-tag type: literal defaultValue: the-tag

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Client Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are force traced if the <code>x-client-trace-id</code> header is set.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Random Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Overall Sampling</p></div></div></td><td><div><div><p>The target percentage of requests that are traced after all other sampling checks have been applied, such as client-directed, force tracing, and random sampling.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Span name</p></div></div></td><td><div><div><p>The name of the span. If no span name is configured, the API name is used.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Labels</p></div></div></td><td><div><div><p>Array of labels that are added to the trace to be used as span attributes in the trace data.</p></div></div></td><td><div><div><p>Optional</p></div></div></td></tr><tr><td><div><div><p>Label Name</p></div></div></td><td><div><div><p>The name of the label, used as a span attribute name.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Type</p></div></div></td><td><div><div><p>The type of the label specifies where the value for the label is taken from. Supported values are <code>literal</code>, <code>environment</code>, and <code>requestHeader</code>.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Key Name</p></div></div></td><td><div><div><p>The key used to retrieve the value, such as an environment variable or request header name.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Label Default Value</p></div></div></td><td><div><div><p>Default value to use if the key is not found or the retrieved value is empty.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=7637f2f3d8d169069668c2c793159a1ac22e2f5f28ebe3dc32f1e6e9b3fd0e84 url=/mulesoft/current/en-us/gateway/1.12/policies-included-traffic-management-route.md -->

---
product: Omni Gateway
version: 1.12
keywords: route, traffic management, upstream service
---

# Traffic Management for Multiple Upstream Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Flex Gateway running in Local Mode. To configure
> multiple upstream services for Flex Gateway running in Connected Mode, see
> [Multiple Upstream Services for Flex Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Flex Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Flex Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about adding weight percentages, refer to
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.12/policies-included-traffic-management).

To allow routing requests to a `Service` when an `ApiInstance` does not include `spec.services`, you
must define a `PolicyBinding` configuration with the Traffic Management for Multiple Upstream
Services (`route`) policy. You don’t need to configure a `route` policy if a custom policy is
managing requests.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route config: destinationPath: <string> // OPTIONAL, default: "/" destinationRef:
name: <string> // REQUIRED kind: <string> // OPTIONAL, default: "Service" namespace: <string> //
OPTIONAL, default: "" rules:

- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>destinationPath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"/"</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.kind</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"Service"</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>destinationRef.namespace</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

You can define an `ApiInstance` configuration that does not include the `spec.services` parameter:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-http
spec:
  address: http://0.0.0.0:8080/api
```

Given the absence of the `spec.services` parameter, you must define the `route` policy in a
`PolicyBinding` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-httpbin-route
spec:
  targetRef:
    name: ingress-http
  policyRef:
    name: route
  config:
    destinationPath: /orders
    destinationRef:
      name: orders-svc
  rules:
    - path: /v1(/.*)
```

The related `Service` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: orders-svc
spec:
  address: https://orders.svc.local:443/
```

## Determining a Request Path

The following table describes all the possible parameter combinations, with examples of the
attributes that determine routing and the expected transformation of a request’s path. The columns
refer to data values of the attributes in the previous configuration examples.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>ApiInstance .address .path</th><th>PolicyBinding(route) .rules .path</th><th>PolicyBinding(route) .config .destinationPath</th><th>Input Path</th><th>Output Path</th></tr></thead><tbody><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/items</p></td></tr><tr><td><p>/api</p></td><td><p>/checkout()</p></td><td><p>/orders</p></td><td><p>/api/checkout</p></td><td><p>/orders</p></td></tr><tr><td><p>/api</p></td><td><p>/api/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>&lt;no match&gt; (expected a path like /api/api/v1/items)</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/us/42</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>/orders</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/orders/us/42</p></td></tr></tbody></table>

## Route Requests to an Unrelated Upstream Path

To route requests to an upstream path unrelated to the request path, add an empty capture group,
`()`, to `rules.path`. Flex Gateway appends only captured text to `destinationPath`, so with an
empty group it sends the request to `destinationPath` unchanged.

This is useful for SOAP services, where clients call a fixed WSDL URL and the `SOAPAction` header
determines the operation.

For example, this configuration routes `/api/masterdata/CustomerService` to
`[https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service](https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service)`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-soap
spec:
  address: http://0.0.0.0:8080/api/masterdata
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-soap-route
spec:
  targetRef:
    name: ingress-soap
  policyRef:
    name: route
  config:
    destinationPath: /sap/bc/srt/scs/sap/customer_service
    destinationRef:
      name: soap-svc
  rules:
    - path: /CustomerService()
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: soap-svc
spec:
  address: https://soap.svc.local:443/
```

## See Also

- [Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.12/policies-included-traffic-management)

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-publish-api-multiple-services)

<!-- document id=59694a3b597f6778fe94182d0f7cc86ffebfc944d03936f5b0facdd7d52e92ae url=/mulesoft/current/en-us/gateway/1.13/policies-included-traffic-management-route.md -->

---
product: Omni Gateway
version: 1.13
keywords: route, traffic management, upstream service
---

# Traffic Management for Multiple Upstream Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-route-release-notes">Traffic Management for Multiple Upstream Services</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Omni Gateway running in Local Mode. To configure
> multiple upstream services for Omni Gateway running in Connected Mode, see
> [Multiple Upstream Services for Omni Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Omni Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Omni Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about adding weight percentages, refer to
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.13/policies-included-traffic-management).

To allow routing requests to a `Service` when an `ApiInstance` does not include `spec.services`, you
must define a `PolicyBinding` configuration with the Traffic Management for Multiple Upstream
Services (`route`) policy. You don’t need to configure a `route` policy if a custom policy is
managing requests.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route config: destinationPath: <string> // OPTIONAL, default: "/" destinationRef:
name: <string> // REQUIRED kind: <string> // OPTIONAL, default: "Service" namespace: <string> //
OPTIONAL, default: "" rules:

- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>destinationPath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"/"</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.kind</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"Service"</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>destinationRef.namespace</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

You can define an `ApiInstance` configuration that does not include the `spec.services` parameter:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-http
spec:
  address: http://0.0.0.0:8080/api
```

Given the absence of the `spec.services` parameter, you must define the `route` policy in a
`PolicyBinding` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-httpbin-route
spec:
  targetRef:
    name: ingress-http
  policyRef:
    name: route
  config:
    destinationPath: /orders
    destinationRef:
      name: orders-svc
  rules:
    - path: /v1(/.*)
```

The related `Service` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: orders-svc
spec:
  address: https://orders.svc.local:443/
```

## Determining a Request Path

The following table describes all the possible parameter combinations, with examples of the
attributes that determine routing and the expected transformation of a request’s path. The columns
refer to data values of the attributes in the previous configuration examples.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>ApiInstance .address .path</th><th>PolicyBinding(route) .rules .path</th><th>PolicyBinding(route) .config .destinationPath</th><th>Input Path</th><th>Output Path</th></tr></thead><tbody><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/items</p></td></tr><tr><td><p>/api</p></td><td><p>/checkout()</p></td><td><p>/orders</p></td><td><p>/api/checkout</p></td><td><p>/orders</p></td></tr><tr><td><p>/api</p></td><td><p>/api/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>&lt;no match&gt; (expected a path like /api/api/v1/items)</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/us/42</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>/orders</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/orders/us/42</p></td></tr></tbody></table>

## Route Requests to an Unrelated Upstream Path

To route requests to an upstream path unrelated to the request path, add an empty capture group
(`()`) to `rules.path`. Omni Gateway appends only captured text to `destinationPath`, so with an
empty group it sends the request to `destinationPath` unchanged.

This is useful for SOAP services, where clients call a fixed WSDL URL and the `SOAPAction` header
determines the operation.

For example, this configuration routes `/api/masterdata/CustomerService` to
`[https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service](https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service)`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-soap
spec:
  address: http://0.0.0.0:8080/api/masterdata
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-soap-route
spec:
  targetRef:
    name: ingress-soap
  policyRef:
    name: route
  config:
    destinationPath: /sap/bc/srt/scs/sap/customer_service
    destinationRef:
      name: soap-svc
  rules:
    - path: /CustomerService()
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: soap-svc
spec:
  address: https://soap.svc.local:443/
```

## See Also

- [Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.13/policies-included-traffic-management)

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-publish-api-multiple-services)

<!-- document id=7d598de51d551c7a352640a55341cbe207cb56d2ed6a5085e3ed66bf26e2ee93 url=/mulesoft/current/en-us/gateway/1.9/policies-included-traffic-management-route.md -->

---
product: Omni Gateway
version: 1.9
keywords: route, traffic management, upstream service
---

# Traffic Management for Multiple Upstream Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Flex Gateway running in Local Mode. To configure
> multiple upstream services for Flex Gateway running in Connected Mode, see
> [Multiple Upstream Services for Flex Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Flex Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Flex Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about adding weight percentages, refer to
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.9/policies-included-traffic-management).

To allow routing requests to a `Service` when an `ApiInstance` does not include `spec.services`, you
must define a `PolicyBinding` configuration with the Traffic Management for Multiple Upstream
Services (`route`) policy. You don’t need to configure a `route` policy if a custom policy is
managing requests.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route config: destinationPath: <string> // OPTIONAL, default: "/" destinationRef:
name: <string> // REQUIRED kind: <string> // OPTIONAL, default: "Service" namespace: <string> //
OPTIONAL, default: "" rules:

- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>destinationPath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"/"</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.kind</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"Service"</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>destinationRef.namespace</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

You can define an `ApiInstance` configuration that does not include the `spec.services` parameter:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-http
spec:
  address: http://0.0.0.0:8080/api
```

Given the absence of the `spec.services` parameter, you must define the `route` policy in a
`PolicyBinding` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-httpbin-route
spec:
  targetRef:
    name: ingress-http
  policyRef:
    name: route
  config:
    destinationPath: /orders
    destinationRef:
      name: orders-svc
  rules:
    - path: /v1(/.*)
```

The related `Service` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: orders-svc
spec:
  address: https://orders.svc.local:443/
```

## Determining a Request Path

The following table describes all the possible parameter combinations, with examples of the
attributes that determine routing and the expected transformation of a request’s path. The columns
refer to data values of the attributes in the previous configuration examples.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>ApiInstance .address .path</th><th>PolicyBinding(route) .rules .path</th><th>PolicyBinding(route) .config .destinationPath</th><th>Input Path</th><th>Output Path</th></tr></thead><tbody><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/items</p></td></tr><tr><td><p>/api</p></td><td><p>/checkout()</p></td><td><p>/orders</p></td><td><p>/api/checkout</p></td><td><p>/orders</p></td></tr><tr><td><p>/api</p></td><td><p>/api/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>&lt;no match&gt; (expected a path like /api/api/v1/items)</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/us/42</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>/orders</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/orders/us/42</p></td></tr></tbody></table>

## Route Requests to an Unrelated Upstream Path

To route requests to an upstream path unrelated to the request path, add an empty capture group,
`()`, to `rules.path`. Flex Gateway appends only captured text to `destinationPath`, so with an
empty group it sends the request to `destinationPath` unchanged.

This is useful for SOAP services, where clients call a fixed WSDL URL and the `SOAPAction` header
determines the operation.

For example, this configuration routes `/api/masterdata/CustomerService` to
`[https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service](https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service)`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-soap
spec:
  address: http://0.0.0.0:8080/api/masterdata
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-soap-route
spec:
  targetRef:
    name: ingress-soap
  policyRef:
    name: route
  config:
    destinationPath: /sap/bc/srt/scs/sap/customer_service
    destinationRef:
      name: soap-svc
  rules:
    - path: /CustomerService()
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: soap-svc
spec:
  address: https://soap.svc.local:443/
```

## See Also

- [Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/1.9/policies-included-traffic-management)

- [Publishing an API with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-publish-api-multiple-services)

<!-- document id=f0f4f118c5f9aec6d6880ea5cd03c5cee23ecea7a7aa3cba5cc92ca7e96c4e0d url=/mulesoft/current/en-us/gateway/latest/policies-included-traffic-management-route.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: route, traffic management, upstream service
---

# Traffic Management for Multiple Upstream Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-route-release-notes">Traffic Management for Multiple Upstream Services</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Omni Gateway running in Local Mode. To configure
> multiple upstream services for Omni Gateway running in Connected Mode, see
> [Multiple Upstream Services for Omni Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Omni Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Omni Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about adding weight percentages, refer to
[Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management).

To allow routing requests to a `Service` when an `ApiInstance` does not include `spec.services`, you
must define a `PolicyBinding` configuration with the Traffic Management for Multiple Upstream
Services (`route`) policy. You don’t need to configure a `route` policy if a custom policy is
managing requests.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route config: destinationPath: <string> // OPTIONAL, default: "/" destinationRef:
name: <string> // REQUIRED kind: <string> // OPTIONAL, default: "Service" namespace: <string> //
OPTIONAL, default: "" rules:

- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>destinationPath</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"/"</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>destinationRef.kind</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>"Service"</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>destinationRef.namespace</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>""</p></div></div></td><td><div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

### Resource Configuration Example

You can define an `ApiInstance` configuration that does not include the `spec.services` parameter:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-http
spec:
  address: http://0.0.0.0:8080/api
```

Given the absence of the `spec.services` parameter, you must define the `route` policy in a
`PolicyBinding` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-httpbin-route
spec:
  targetRef:
    name: ingress-http
  policyRef:
    name: route
  config:
    destinationPath: /orders
    destinationRef:
      name: orders-svc
  rules:
    - path: /v1(/.*)
```

The related `Service` configuration:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: orders-svc
spec:
  address: https://orders.svc.local:443/
```

## Determining a Request Path

The following table describes all the possible parameter combinations, with examples of the
attributes that determine routing and the expected transformation of a request’s path. The columns
refer to data values of the attributes in the previous configuration examples.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>ApiInstance .address .path</th><th>PolicyBinding(route) .rules .path</th><th>PolicyBinding(route) .config .destinationPath</th><th>Input Path</th><th>Output Path</th></tr></thead><tbody><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/api/v1/items</p></td></tr><tr><td><p>&lt;empty&gt;</p></td><td><p>/api(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/items</p></td><td><p>/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/v1/items</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.*)</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>/orders/items</p></td></tr><tr><td><p>/api</p></td><td><p>/checkout()</p></td><td><p>/orders</p></td><td><p>/api/checkout</p></td><td><p>/orders</p></td></tr><tr><td><p>/api</p></td><td><p>/api/v1/.*</p></td><td><p>/orders</p></td><td><p>/api/v1/items</p></td><td><p>&lt;no match&gt; (expected a path like /api/api/v1/items)</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>&lt;empty&gt;</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/us/42</p></td></tr><tr><td><p>/api</p></td><td><p>/v1(/.)/items(/.)</p></td><td><p>/orders</p></td><td><p>/api/v1/us/items/42</p></td><td><p>/orders/us/42</p></td></tr></tbody></table>

## Route Requests to an Unrelated Upstream Path

To route requests to an upstream path unrelated to the request path, add an empty capture group,
`()`, to `rules.path`. Omni Gateway appends only captured text to `destinationPath`, so with an
empty group it sends the request to `destinationPath` unchanged.

This is useful for SOAP services, where clients call a fixed WSDL URL and the `SOAPAction` header
determines the operation.

For example, this configuration routes `/api/masterdata/CustomerService` to
`[https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service](https://soap.svc.local:443/sap/bc/srt/scs/sap/customer_service)`:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-soap
spec:
  address: http://0.0.0.0:8080/api/masterdata
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-soap-route
spec:
  targetRef:
    name: ingress-soap
  policyRef:
    name: route
  config:
    destinationPath: /sap/bc/srt/scs/sap/customer_service
    destinationRef:
      name: soap-svc
  rules:
    - path: /CustomerService()
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: soap-svc
spec:
  address: https://soap.svc.local:443/
```

## See Also

- [Traffic Management for Multiple Upstream Services (Weighted)](https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management)

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-api-multiple-services)

<!-- document id=381d7bcc71bdef2e70148896a1606db1652c5ab3f9a9d8483cefffec59be82be url=/mulesoft/current/en-us/gateway/1.12/policies-included-traffic-management.md -->

---
product: Omni Gateway
version: 1.12
keywords: route weight, traffic management, multiple upstream services
---

# Traffic Management for Multiple Upstream Services (Weighted)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services (Weighted)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages weighted API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.5.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Flex Gateway running in Local Mode. To configure
> multiple upstream services for Flex Gateway running in Connected Mode, see
> [Multiple Upstream Services for Flex Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Flex Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Flex Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Flex Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about configuring non-weighted traffic, refer to
[Traffic Management for Multiple Upstream Services](https://docs.mulesoft.com/gateway/1.12/policies-included-traffic-management-route).

API instances with multiple upstream services in Local Mode are configured by using `PolicyBinding`
YAML configuration resources. Each `route-weighted` resource defines a single route. To add
additional routes, add multiple `route-weighted` resources.

For a tutorial about how to publish an API instance with this policy applied, see
[Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-publish-api-multiple-services).

> [!NOTE] Deploying APIs with multiple upstream services does not affect the
> [Outbound Transport Layer Security policy](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound). You can apply an
> Outbound TLS policy to each upstream service.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route-weighted config: routes:

- weight: <int> // REQUIRED, max\_value=100, min\_value=1 destinationPath: <string> // OPTIONAL,
  default: "/" destinationRef: name: <string> // REQUIRED rules:
- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>routes</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of API upstream services.<br>At least one upstream is required.</p></div></div></td></tr><tr><td><div><div><p><code>routes.weight</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Weight of total requests sent to this upstream service.<br>The percentage of traffic sent to that upstream service is the upstream service’s weight divided by total weight of all upstream services.</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationPath</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The Traffic Management policy directs traffic to different sets of upstream services by using
multiple routes with a defined route order and individual rulesets to direct traffic to different
sets of upstream services.

In the following diagram, different routes manage requests to flight information databases and to a
customer service application. Route one has two upstream services defined, which directs 70% of
requests to a stable database and 30% of requests to a beta database.

![Flex Gateway manages the traffic to multiple upstream services](/mulesoft/current/en-us/gateway/1.12/_images/multiple-upstreams.png)

To achieve this configuration, bind two `route-weighted` resources to the exposed API instance. One
`route-weighted` resource directs traffic to the flight information database, and the other
`route-weighted` resource directs traffic to the customer service application.

### Upstream Services

You can use multiple upstream services in a single route to direct requests to similar services. For
example, to test the performance of a new beta upstream service without sending all traffic to the
new service, you can direct half of the traffic to a stable upstream service and half to the new
upstream service.

The upstream service within the route that each request is sent to is random and independent of any
previous request. The `routes.weight` value defines the chance of a request being sent to a
particular upstream service. The percentage of traffic sent to that upstream service is the
upstream’s `routes.weight` divided by the total weight of all upstream services. For example, if
there are two upstream services with weight `1`, each receives 50% of the traffic to that route. If
the weight values are `1` and `3`, one route would receive 25% of traffic and the other 75%.

Because any upstream service within a route can receive any request, all upstream services within
the same route must adhere to the same API contract.

### Route Rules

You can direct requests to different routes by using route rules. Requests must meet the rules for
only one of the rulesets in the route.

Rulesets refer to any combination of the four rules: `path`, `method`, `headers`, and `host`. You
can use multiple rulesets to support different combinations of rules.

All rules are optional. If a rule is not included in a ruleset, that rule is ignored. For example,
not specifying a host means that the route can service any host if the request meets the other route
rules. Not defining any rule means that the route can service every request.

If a request does not meet the rules for any route, Flex Gateway returns a `404` error code.

### Route Order

In addition to using route rules, you can direct requests to different routes by using policy
ordering.

To order policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.12/policies-reorder)

Setting the policy order sets the order in which traffic is directed to the routes. Flex Gateway
directs requests to the first route if the request meets one of the route rulesets. Therefore, route
ordering is very important when a request can meet the route rules of multiple routes.

For example, in a configuration in which route one has the `GET` method defined as a rule and route
two has no route rules defined, all `GET` requests are sent to route one and all other requests are
sent to route two. If the route order was reversed and route one had no route rules, Flex Gateway
would direct all requests to route one before any `GET` requests could reach route two.

## See Also

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-publish-api-multiple-services)

<!-- document id=38916f23ec75f69e3e2b5c69b88f975bad4dd3491deda2b7313ab319b4da42ad url=/mulesoft/current/en-us/gateway/1.13/policies-included-traffic-management.md -->

---
product: Omni Gateway
version: 1.13
keywords: route weight, traffic management, multiple upstream services
---

# Traffic Management for Multiple Upstream Services (Weighted)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services (Weighted)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages weighted API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.5.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-release-notes">Traffic Management for Multiple Upstream Services (Weighted)</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Omni Gateway running in Local Mode. To configure
> multiple upstream services for Omni Gateway running in Connected Mode, see
> [Multiple Upstream Services for Omni Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Omni Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Omni Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Omni Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about configuring non-weighted traffic, refer to
[Traffic Management for Multiple Upstream Services](https://docs.mulesoft.com/gateway/1.13/policies-included-traffic-management-route).

API instances with multiple upstream services in Local Mode are configured by using `PolicyBinding`
YAML configuration resources. Each `route-weighted` resource defines a single route. To add
additional routes, add multiple `route-weighted` resources.

For a tutorial about how to publish an API instance with this policy applied, see
[Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-publish-api-multiple-services).

> [!NOTE] Deploying APIs with multiple upstream services does not affect the
> [Outbound Transport Layer Security policy](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound). You can apply an
> Outbound TLS policy to each upstream service.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route-weighted config: routes:

- weight: <int> // REQUIRED, max\_value=100, min\_value=1 destinationPath: <string> // OPTIONAL,
  default: "/" destinationRef: name: <string> // REQUIRED rules:
- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>routes</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of API upstream services.<br>At least one upstream is required.</p></div></div></td></tr><tr><td><div><div><p><code>routes.weight</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Weight of total requests sent to this upstream service.<br>The percentage of traffic sent to that upstream service is the upstream service’s weight divided by total weight of all upstream services.</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationPath</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The Traffic Management policy directs traffic to different sets of upstream services by using
multiple routes with a defined route order and individual rulesets to direct traffic to different
sets of upstream services.

In the following diagram, different routes manage requests to flight information databases and to a
customer service application. Route one has two upstream services defined, which directs 70% of
requests to a stable database and 30% of requests to a beta database.

![Omni Gateway manages the traffic to multiple upstream services](/mulesoft/current/en-us/gateway/1.13/_images/multiple-upstreams.png)

To achieve this configuration, bind two `route-weighted` resources to the exposed API instance. One
`route-weighted` resource directs traffic to the flight information database, and the other
`route-weighted` resource directs traffic to the customer service application.

### Upstream Services

You can use multiple upstream services in a single route to direct requests to similar services. For
example, to test the performance of a new beta upstream service without sending all traffic to the
new service, you can direct half of the traffic to a stable upstream service and half to the new
upstream service.

The upstream service within the route that each request is sent to is random and independent of any
previous request. The `routes.weight` value defines the chance of a request being sent to a
particular upstream service. The percentage of traffic sent to that upstream service is the
upstream’s `routes.weight` divided by the total weight of all upstream services. For example, if
there are two upstream services with weight `1`, each receives 50% of the traffic to that route. If
the weight values are `1` and `3`, one route would receive 25% of traffic and the other 75%.

Because any upstream service within a route can receive any request, all upstream services within
the same route must adhere to the same API contract.

### Route Rules

You can direct requests to different routes by using route rules. Requests must meet the rules for
only one of the rulesets in the route.

Rulesets refer to any combination of the four rules: `path`, `method`, `headers`, and `host`. You
can use multiple rulesets to support different combinations of rules.

All rules are optional. If a rule is not included in a ruleset, that rule is ignored. For example,
not specifying a host means that the route can service any host if the request meets the other route
rules. Not defining any rule means that the route can service every request.

If a request does not meet the rules for any route, Omni Gateway returns a `404` error code.

### Route Order

In addition to using route rules, you can direct requests to different routes by using policy
ordering.

To order policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder)

Setting the policy order sets the order in which traffic is directed to the routes. Omni Gateway
directs requests to the first route if the request meets one of the route rulesets. Therefore, route
ordering is very important when a request can meet the route rules of multiple routes.

For example, in a configuration in which route one has the `GET` method defined as a rule and route
two has no route rules defined, all `GET` requests are sent to route one and all other requests are
sent to route two. If the route order was reversed and route one had no route rules, Omni Gateway
would direct all requests to route one before any `GET` requests could reach route two.

## See Also

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-publish-api-multiple-services)

<!-- document id=af1dde92a95c870027a4c5740187d4c082d82968db6c007b83a927c00a9714e6 url=/mulesoft/current/en-us/gateway/1.9/policies-included-traffic-management.md -->

---
product: Omni Gateway
version: 1.9
keywords: route weight, traffic management, multiple upstream services
---

# Traffic Management for Multiple Upstream Services (Weighted)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services (Weighted)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages weighted API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.5.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Flex Gateway running in Local Mode. To configure
> multiple upstream services for Flex Gateway running in Connected Mode, see
> [Multiple Upstream Services for Flex Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Flex Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Flex Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Flex Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about configuring non-weighted traffic, refer to
[Traffic Management for Multiple Upstream Services](https://docs.mulesoft.com/gateway/1.9/policies-included-traffic-management-route).

API instances with multiple upstream services in Local Mode are configured by using `PolicyBinding`
YAML configuration resources. Each `route-weighted` resource defines a single route. To add
additional routes, add multiple `route-weighted` resources.

For a tutorial about how to publish an API instance with this policy applied, see
[Publishing an API with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-publish-api-multiple-services).

> [!NOTE] Deploying APIs with multiple upstream services does not affect the
> [Outbound Transport Layer Security policy](https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound). You can apply an
> Outbound TLS policy to each upstream service.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route-weighted config: routes:

- weight: <int> // REQUIRED, max\_value=100, min\_value=1 destinationPath: <string> // OPTIONAL,
  default: "/" destinationRef: name: <string> // REQUIRED rules:
- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>routes</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of API upstream services.<br>At least one upstream is required.</p></div></div></td></tr><tr><td><div><div><p><code>routes.weight</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Weight of total requests sent to this upstream service.<br>The percentage of traffic sent to that upstream service is the upstream service’s weight divided by total weight of all upstream services.</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationPath</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The Traffic Management policy directs traffic to different sets of upstream services by using
multiple routes with a defined route order and individual rulesets to direct traffic to different
sets of upstream services.

In the following diagram, different routes manage requests to flight information databases and to a
customer service application. Route one has two upstream services defined, which directs 70% of
requests to a stable database and 30% of requests to a beta database.

![Flex Gateway manages the traffic to multiple upstream services](/mulesoft/current/en-us/gateway/1.9/_images/multiple-upstreams.png)

To achieve this configuration, bind two `route-weighted` resources to the exposed API instance. One
`route-weighted` resource directs traffic to the flight information database, and the other
`route-weighted` resource directs traffic to the customer service application.

### Upstream Services

You can use multiple upstream services in a single route to direct requests to similar services. For
example, to test the performance of a new beta upstream service without sending all traffic to the
new service, you can direct half of the traffic to a stable upstream service and half to the new
upstream service.

The upstream service within the route that each request is sent to is random and independent of any
previous request. The `routes.weight` value defines the chance of a request being sent to a
particular upstream service. The percentage of traffic sent to that upstream service is the
upstream’s `routes.weight` divided by the total weight of all upstream services. For example, if
there are two upstream services with weight `1`, each receives 50% of the traffic to that route. If
the weight values are `1` and `3`, one route would receive 25% of traffic and the other 75%.

Because any upstream service within a route can receive any request, all upstream services within
the same route must adhere to the same API contract.

### Route Rules

You can direct requests to different routes by using route rules. Requests must meet the rules for
only one of the rulesets in the route.

Rulesets refer to any combination of the four rules: `path`, `method`, `headers`, and `host`. You
can use multiple rulesets to support different combinations of rules.

All rules are optional. If a rule is not included in a ruleset, that rule is ignored. For example,
not specifying a host means that the route can service any host if the request meets the other route
rules. Not defining any rule means that the route can service every request.

If a request does not meet the rules for any route, Flex Gateway returns a `404` error code.

### Route Order

In addition to using route rules, you can direct requests to different routes by using policy
ordering.

To order policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.9/policies-reorder)

Setting the policy order sets the order in which traffic is directed to the routes. Flex Gateway
directs requests to the first route if the request meets one of the route rulesets. Therefore, route
ordering is very important when a request can meet the route rules of multiple routes.

For example, in a configuration in which route one has the `GET` method defined as a rule and route
two has no route rules defined, all `GET` requests are sent to route one and all other requests are
sent to route two. If the route order was reversed and route one had no route rules, Flex Gateway
would direct all requests to route one before any `GET` requests could reach route two.

## See Also

- [Publishing an API with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-publish-api-multiple-services)

<!-- document id=87f6954937873d85520dfdb3f889c51dca2e7ea8f88eb738bb31e0265f4c3b06 url=/mulesoft/current/en-us/gateway/latest/policies-included-traffic-management.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: route weight, traffic management, multiple upstream services
---

# Traffic Management for Multiple Upstream Services (Weighted)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Traffic Management for Multiple Upstream Services (Weighted)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Manages weighted API instance traffic to multiple upstream services from a single consumer endpoint</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.5.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/traffic-management-release-notes">Traffic Management for Multiple Upstream Services (Weighted)</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following information applies only to Omni Gateway running in Local Mode. To configure
> multiple upstream services for Omni Gateway running in Connected Mode, see
> [Multiple Upstream Services for Omni Gateway Running in Connected Mode](https://docs.mulesoft.com/api-manager/latest/create-instance-task-flex#traffic-management).

## Summary

Omni Gateway running in Local Mode supports API instances that expose multiple upstream services
through a single consumer endpoint.

Omni Gateway manages request traffic by using different routes that can each direct traffic to
multiple upstream services. Omni Gateway directs traffic to the routes by using the route order and
the individual route’s rules. Additionally, you can add a weighted percentage to each upstream
service within a route to manage the percentage of requests sent to the upstream service. For
information about configuring non-weighted traffic, refer to
[Traffic Management for Multiple Upstream Services](https://docs.mulesoft.com/gateway/latest/policies-included-traffic-management-route).

API instances with multiple upstream services in Local Mode are configured by using `PolicyBinding`
YAML configuration resources. Each `route-weighted` resource defines a single route. To add
additional routes, add multiple `route-weighted` resources.

For a tutorial about how to publish an API instance with this policy applied, see
[Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-api-multiple-services).

> [!NOTE] Deploying APIs with multiple upstream services does not affect the
> [Outbound Transport Layer Security policy](https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound). You can apply an
> Outbound TLS policy to each upstream service.

## Configuring Policy Parameters

Refer to the following policy definition and table of parameters:

policyRef: name: route-weighted config: routes:

- weight: <int> // REQUIRED, max\_value=100, min\_value=1 destinationPath: <string> // OPTIONAL,
  default: "/" destinationRef: name: <string> // REQUIRED rules:
- path: <URL-regex> // OPTIONAL, Example: (.\*) methods: <regex-string> // OPTIONAL, Example:
  GET|POST headers: <header-name>: <regex-string> // OPTIONAL host: <regex-string> // OPTIONAL

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>routes</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of API upstream services.<br>At least one upstream is required.</p></div></div></td></tr><tr><td><div><div><p><code>routes.weight</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Weight of total requests sent to this upstream service.<br>The percentage of traffic sent to that upstream service is the upstream service’s weight divided by total weight of all upstream services.</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationPath</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Path of the upstream service</p></div></div></td></tr><tr><td><div><div><p><code>routes.destinationRef.name</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the upstream service as defined in the <code>Service</code> configuration resource</p></div></div></td></tr><tr><td><div><div><p><code>rules</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array of rulesets for this route.<br>Each route can support multiple rulesets.</p></div></div></td></tr><tr><td><div><div><p><code>rules.path</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request path that the route can service.<br>You can define only one “URI Template Regex" path for each ruleset. Only requests with the defined path are sent to this route.</p></div></div></td></tr><tr><td><div><div><p><code>rules.methods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines the types of request methods that the route can service.<br>You can select multiple methods for each ruleset. Only requests that are one of the defined methods are sent to this route. Supported values are <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>, <code>OPTIONS</code>, <code>HEAD</code>, <code>TRACE</code>, and <code>CONNECT</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rules.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Array that defines what headers and regular expression value must be present for this route to service the request.<br>Only requests that meet all of the specified header requirements are sent to this route. Additional headers present in the request that are not specifically defined in the rules are ignored.</p></div></div></td></tr><tr><td><div><div><p><code>rules.host</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty</p></div></div></td><td><div><div><p>Request host URL that the route can service.<br>You can define only one host URL for each ruleset. Only requests made from the defined host are sent to this route.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The Traffic Management policy directs traffic to different sets of upstream services by using
multiple routes with a defined route order and individual rulesets to direct traffic to different
sets of upstream services.

In the following diagram, different routes manage requests to flight information databases and to a
customer service application. Route one has two upstream services defined, which directs 70% of
requests to a stable database and 30% of requests to a beta database.

![Omni Gateway manages the traffic to multiple upstream services](/mulesoft/current/en-us/gateway/latest/_images/multiple-upstreams.png)

To achieve this configuration, bind two `route-weighted` resources to the exposed API instance. One
`route-weighted` resource directs traffic to the flight information database, and the other
`route-weighted` resource directs traffic to the customer service application.

### Upstream Services

You can use multiple upstream services in a single route to direct requests to similar services. For
example, to test the performance of a new beta upstream service without sending all traffic to the
new service, you can direct half of the traffic to a stable upstream service and half to the new
upstream service.

The upstream service within the route that each request is sent to is random and independent of any
previous request. The `routes.weight` value defines the chance of a request being sent to a
particular upstream service. The percentage of traffic sent to that upstream service is the
upstream’s `routes.weight` divided by the total weight of all upstream services. For example, if
there are two upstream services with weight `1`, each receives 50% of the traffic to that route. If
the weight values are `1` and `3`, one route would receive 25% of traffic and the other 75%.

Because any upstream service within a route can receive any request, all upstream services within
the same route must adhere to the same API contract.

### Route Rules

You can direct requests to different routes by using route rules. Requests must meet the rules for
only one of the rulesets in the route.

Rulesets refer to any combination of the four rules: `path`, `method`, `headers`, and `host`. You
can use multiple rulesets to support different combinations of rules.

All rules are optional. If a rule is not included in a ruleset, that rule is ignored. For example,
not specifying a host means that the route can service any host if the request meets the other route
rules. Not defining any rule means that the route can service every request.

If a request does not meet the rules for any route, Omni Gateway returns a `404` error code.

### Route Order

In addition to using route rules, you can direct requests to different routes by using policy
ordering.

To order policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/latest/policies-reorder)

Setting the policy order sets the order in which traffic is directed to the routes. Omni Gateway
directs requests to the first route if the request meets one of the route rulesets. Therefore, route
ordering is very important when a request can meet the route rules of multiple routes.

For example, in a configuration in which route one has the `GET` method defined as a rule and route
two has no route rules defined, all `GET` requests are sent to route one and all other requests are
sent to route two. If the route order was reversed and route one had no route rules, Omni Gateway
would direct all requests to route one before any `GET` requests could reach route two.

## See Also

- [Publishing an API Instance with Multiple Upstream Services in Local Mode](https://docs.mulesoft.com/gateway/latest/local-publish-api-multiple-services)

<!-- document id=97e3925a4963c19f69ff2ed611fa73fc1915cec162b88e3384d04f00cd48265b url=/mulesoft/current/en-us/gateway/1.12/policies-included-tls.md -->

---
product: Omni Gateway
version: 1.12
keywords: tls, mtls, transport layer security, inbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Inbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Inbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables authentication between a client and the API proxy</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0 (inbound mTLS: v1.3.0)</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Flex Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config).

## Summary

Flex Gateway supports inbound Transport Layer Security (TLS) and inbound mutual authentication TLS
(mTLS) in Local Mode.

To apply inbound TLS in Local Mode, use the
[Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config) tutorial and refer
to the following configuration files in this documentation.

You can configure an inbound TLS context to enable authentication between a client and the API
instance (HTTPS) by binding the TLS policy to your API instance or to all instances in your Flex
Gateway.

Flex Gateway implements port-level inbound TLS, meaning if you apply an inbound TLS to an API
instance that shares a port with other instances, the same inbound TLS context is applied to all
instances sharing the port. Flex Gateway supports multiple TLS certificates on a single gateway, but
you must apply the certificates to unique ports. If you apply inbound TLS to one API instance, you
do not need to apply the same inbound TLS context to instances that share that port. Consequently,
you cannot apply different inbound TLS contexts to API instances that share the same port.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

## Configuring Policy Parameters

To use HTTPS as your schema when creating an API instance using Flex Gateway as your runtime, you
must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls config: requireClientCertificate: <boolean> // OPTIONAL trustedCA: <string>
// OPTIONAL certificate: // OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn:
<array> // OPTIONAL minversion: <string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers:
<array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, see [TLS Cipher Support on Flex Gateway](#local-support)
for the supported ciphers.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>requireClientCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables inbound mTLS.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>requireClientCertificate</code> is true</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the client certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Flex Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format). For the supported ciphers, see <a href="#local-support">TLS Cipher Support on Flex Gateway</a>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS either for a specific API instance or for all
API instances running on your Flex Gateway.

#### Apply TLS Configuration to All API Instances

**Sample configuration for adding inbound TLS context for all API instances running on this Flex
Gateway:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: Selector
    selector:
      kind: ApiInstance
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply TLS Configuration to a Specific API Instance

**Sample configuration for adding inbound TLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-https
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply mTLS Inbound Configuration to a Specific API Instance

**Sample configuration for adding an inbound mTLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls
spec:
  targetRef:
    name: ingress-https
  policyRef:
    name: tls
  config:
    requireClientCertificate: true
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN RSA PRIVATE KEY-----
        # insert private key
        # -----END RSA PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config)

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls-outbound)

<!-- document id=d48715192cac6ed3fabfe915bd370b0841ec559c0d087219387b451bd04088f3 url=/mulesoft/current/en-us/gateway/1.13/policies-included-tls.md -->

---
product: Omni Gateway
version: 1.13
keywords: tls, mtls, transport layer security, inbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Inbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Inbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables authentication between a client and the API proxy</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0 (inbound mTLS: v1.3.0)</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-release-notes">Transport Layer Security (TLS) - Inbound</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Omni Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config).

## Summary

Omni Gateway supports inbound Transport Layer Security (TLS) and inbound mutual authentication TLS
(mTLS) in Local Mode.

To apply inbound TLS in Local Mode, use the
[Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config) tutorial and refer to the
following configuration files in this documentation.

You can configure an inbound TLS context to enable authentication between a client and the API
instance (HTTPS) by binding the TLS policy to your API instance or to all instances in your Omni
Gateway.

Omni Gateway implements port-level inbound TLS, meaning if you apply an inbound TLS to an API
instance that shares a port with other instances, the same inbound TLS context is applied to all
instances sharing the port. Omni Gateway supports multiple TLS certificates on a single gateway, but
you must apply the certificates to unique ports. If you apply inbound TLS to one API instance, you
do not need to apply the same inbound TLS context to instances that share that port. Consequently,
you cannot apply different inbound TLS contexts to API instances that share the same port.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

## Configuring Policy Parameters

To use HTTPS as your schema when creating an API instance using Omni Gateway as your runtime, you
must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls config: requireClientCertificate: <boolean> // OPTIONAL trustedCA: <string>
// OPTIONAL certificate: // OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn:
<array> // OPTIONAL minversion: <string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers:
<array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, see [TLS Cipher Support on Omni Gateway](#local-support)
for the supported ciphers.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>requireClientCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables inbound mTLS.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>requireClientCertificate</code> is true</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the client certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format). For the supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS either for a specific API instance or for all
API instances running on your Omni Gateway.

#### Apply TLS Configuration to All API Instances

**Sample configuration for adding inbound TLS context for all API instances running on this Omni
Gateway:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: Selector
    selector:
      kind: ApiInstance
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply TLS Configuration to a Specific API Instance

**Sample configuration for adding inbound TLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-https
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply mTLS Inbound Configuration to a Specific API Instance

**Sample configuration for adding an inbound mTLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls
spec:
  targetRef:
    name: ingress-https
  policyRef:
    name: tls
  config:
    requireClientCertificate: true
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN RSA PRIVATE KEY-----
        # insert private key
        # -----END RSA PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound)

<!-- document id=16e7c2c78a29ddc8ca9e4a51d34d6c99dad12a197895f5c0fab47653020dd142 url=/mulesoft/current/en-us/gateway/1.9/policies-included-tls.md -->

---
product: Omni Gateway
version: 1.9
keywords: tls, mtls, transport layer security, inbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Inbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Inbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables authentication between a client and the API proxy</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><div><div><p>v1.0.0 (inbound mTLS: v1.3.0)</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Flex Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config).

## Summary

Flex Gateway supports inbound Transport Layer Security (TLS) and inbound mutual authentication TLS
(mTLS) in Local Mode.

To apply inbound TLS in Local Mode, use the
[Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config) tutorial and refer
to the following configuration files in this documentation.

You can configure an inbound TLS context to enable authentication between a client and the API
instance (HTTPS) by binding the TLS policy to your API instance or to all instances in your Flex
Gateway.

Flex Gateway implements port-level inbound TLS, meaning if you apply an inbound TLS to an API
instance that shares a port with other instances, the same inbound TLS context is applied to all
instances sharing the port. Flex Gateway supports multiple TLS certificates on a single gateway, but
you must apply the certificates to unique ports. If you apply inbound TLS to one API instance, you
do not need to apply the same inbound TLS context to instances that share that port. Consequently,
you cannot apply different inbound TLS contexts to API instances that share the same port.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

## Configuring Policy Parameters

To use HTTPS as your schema when creating an API instance using Flex Gateway as your runtime, you
must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls config: requireClientCertificate: <boolean> // OPTIONAL trustedCA: <string>
// OPTIONAL certificate: // OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn:
<array> // OPTIONAL minversion: <string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers:
<array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, see [TLS Cipher Support on Flex Gateway](#local-support)
for the supported ciphers.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>requireClientCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables inbound mTLS</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>requireClientCertificate</code> is true</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate used in mTLS</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Flex Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format). For the supported ciphers, see <a href="#local-support">TLS Cipher Support on Flex Gateway</a>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS either for a specific API instance or for all
API instances running on your Flex Gateway.

#### Apply TLS Configuration to All API Instances

**Sample configuration for adding inbound TLS context for all API instances running on this Flex
Gateway:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: Selector
    selector:
      kind: ApiInstance
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply TLS Configuration to a Specific API Instance

**Sample configuration for adding inbound TLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-https
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply mTLS Inbound Configuration to a Specific API Instance

**Sample configuration for adding an inbound mTLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls
spec:
  targetRef:
    name: ingress-https
  policyRef:
    name: tls
  config:
    requireClientCertificate: true
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN RSA PRIVATE KEY-----
        # insert private key
        # -----END RSA PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config)

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls-outbound)

<!-- document id=49bee5d2187b0ab7e4aff93e590e201e338e21298cb87fb1f97afc8dad1df44c url=/mulesoft/current/en-us/gateway/latest/policies-included-tls.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: tls, mtls, transport layer security, inbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Inbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Inbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables authentication between a client and the API proxy</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0 (inbound mTLS: v1.3.0)</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-release-notes">Transport Layer Security (TLS) - Inbound</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Omni Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tls-config).

## Summary

Omni Gateway supports inbound Transport Layer Security (TLS) and inbound mutual authentication TLS
(mTLS) in Local Mode.

To apply inbound TLS in Local Mode, use the
[Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tls-config) tutorial and refer to the
following configuration files in this documentation.

You can configure an inbound TLS context to enable authentication between a client and the API
instance (HTTPS) by binding the TLS policy to your API instance or to all instances in your Omni
Gateway.

Omni Gateway implements port-level inbound TLS, meaning if you apply an inbound TLS to an API
instance that shares a port with other instances, the same inbound TLS context is applied to all
instances sharing the port. Omni Gateway supports multiple TLS certificates on a single gateway, but
you must apply the certificates to unique ports. If you apply inbound TLS to one API instance, you
do not need to apply the same inbound TLS context to instances that share that port. Consequently,
you cannot apply different inbound TLS contexts to API instances that share the same port.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

## Configuring Policy Parameters

To use HTTPS as your schema when creating an API instance using Omni Gateway as your runtime, you
must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls config: requireClientCertificate: <boolean> // OPTIONAL trustedCA: <string>
// OPTIONAL certificate: // OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn:
<array> // OPTIONAL minversion: <string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers:
<array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, see [TLS Cipher Support on Omni Gateway](#local-support)
for the supported ciphers.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>requireClientCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables inbound mTLS.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>requireClientCertificate</code> is true</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the client certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format). For the supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS either for a specific API instance or for all
API instances running on your Omni Gateway.

#### Apply TLS Configuration to All API Instances

**Sample configuration for adding inbound TLS context for all API instances running on this Omni
Gateway:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: Selector
    selector:
      kind: ApiInstance
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply TLS Configuration to a Specific API Instance

**Sample configuration for adding inbound TLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-https
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA
```

#### Apply mTLS Inbound Configuration to a Specific API Instance

**Sample configuration for adding an inbound mTLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls
spec:
  targetRef:
    name: ingress-https
  policyRef:
    name: tls
  config:
    requireClientCertificate: true
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN RSA PRIVATE KEY-----
        # insert private key
        # -----END RSA PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tls-config)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls-outbound)

<!-- document id=eb4bf5290fa03b2449713514e9a54bdd42010d01d0a32a81ef52ce2c82059072 url=/mulesoft/current/en-us/gateway/1.12/policies-included-tls-outbound.md -->

---
product: Omni Gateway
version: 1.12
keywords: tls, mtls, transport layer security, outbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Outbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Outbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables two-way authentication between the API proxy and an upstream service</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Flex version available</strong></p></td><td><div><div><p>v1.4.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Flex Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config).

## Summary

Flex Gateway supports outbound Transport Layer Security (TLS) and outbound mutual authentication TLS
(mTLS) in Local Mode.

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

To apply outbound TLS in Local Mode, use the
[Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config) tutorial and refer
to the following configuration files in this documentation.

You can configure an outbound TLS context to enable authentication between an API instance and an
upstream service by binding the TLS policy to the upstream service.

Unlike inbound TLS, it is not suggested to apply the same outbound TLS context to all API instances
in your Flex Gateway because your API upstream services might come from different providers.
Therefore, no configuration example for outbound TLS on all instances is provided.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

> [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
> Common Name (CN) field is deprecated.
>
> Flex Gateway supports the SAN extension of type `dNSName`.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Configuring Policy Parameters

To enable outbound TLS between an API instance and an upstream service when using Flex Gateway as
your runtime, you must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls-outbound config: skipValidation: <boolean> // REQUIRED certificate: //
OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn: <array> // OPTIONAL minversion:
<string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, ensure that your API upstream supports the listed ciphers.
For the supported ciphers, see [TLS Cipher Support on Flex Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the upstream certificate is not validated.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>skipValidation</code> is false</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the upstream server certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate to present for mTLS. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Flex Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS for a upstream service.

**Sample configuration for adding outbound TLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: tls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: true
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

**Sample configuration for adding outbound mTLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: false
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
```

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-tls-config)

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.12/policies-included-tls)

<!-- document id=a3dbc4c79e356c7eba766a926623748faa98add0b956994814d01d36be546d2c url=/mulesoft/current/en-us/gateway/1.13/policies-included-tls-outbound.md -->

---
product: Omni Gateway
version: 1.13
keywords: tls, mtls, transport layer security, outbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Outbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Outbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables two-way authentication between the API proxy and an upstream service</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni version available</strong></p></td><td><div><div><p>v1.4.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-outbound-release-notes">Transport Layer Security (TLS) - Outbound</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Omni Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config).

## Summary

Omni Gateway supports outbound Transport Layer Security (TLS) and outbound mutual authentication TLS
(mTLS) in Local Mode.

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

To apply outbound TLS in Local Mode, use the
[Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config) tutorial and refer to the
following configuration files in this documentation.

You can configure an outbound TLS context to enable authentication between an API instance and an
upstream service by binding the TLS policy to the upstream service.

Unlike inbound TLS, it is not suggested to apply the same outbound TLS context to all API instances
in your Omni Gateway because your API upstream services might come from different providers.
Therefore, no configuration example for outbound TLS on all instances is provided.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

> [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
> Common Name (CN) field is deprecated.
>
> Omni Gateway supports the SAN extension of type `dNSName`.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Configuring Policy Parameters

To enable outbound TLS between an API instance and an upstream service when using Omni Gateway as
your runtime, you must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls-outbound config: skipValidation: <boolean> // REQUIRED certificate: //
OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn: <array> // OPTIONAL minversion:
<string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, ensure that your API upstream supports the listed ciphers.
For the supported ciphers, see [TLS Cipher Support on Omni Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the upstream certificate is not validated.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>skipValidation</code> is false</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the upstream server certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate to present for mTLS. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS for a upstream service.

**Sample configuration for adding outbound TLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: tls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: true
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

**Sample configuration for adding outbound mTLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: false
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
```

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls)

<!-- document id=56eef2fb3e2ef7fd79bca7776eea287c70fd8040ca5d490702174adacdcfbd78 url=/mulesoft/current/en-us/gateway/1.9/policies-included-tls-outbound.md -->

---
product: Omni Gateway
version: 1.9
keywords: tls, mtls, transport layer security, outbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Outbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Outbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables two-way authentication between the API proxy and an upstream service</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Flex version available</strong></p></td><td><div><div><p>v1.4.0</p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Flex Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config).

## Summary

Flex Gateway supports outbound Transport Layer Security (TLS) and outbound mutual authentication TLS
(mTLS) in Local Mode.

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Flex Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

To apply outbound TLS in Local Mode, use the
[Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config) tutorial and refer
to the following configuration files in this documentation.

You can configure an outbound TLS context to enable authentication between an API instance and an
upstream service by binding the TLS policy to the upstream service.

Unlike inbound TLS, it is not suggested to apply the same outbound TLS context to all API instances
in your Flex Gateway because your API upstream services might come from different providers.
Therefore, no configuration example for outbound TLS on all instances is provided.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

> [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
> Common Name (CN) field is deprecated.
>
> Flex Gateway supports the SAN extension of type `dNSName`.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Configuring Policy Parameters

To enable outbound TLS between an API instance and an upstream service when using Flex Gateway as
your runtime, you must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls-outbound config: skipValidation: <boolean> // REQUIRED certificate: //
OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn: <array> // OPTIONAL minversion:
<string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, ensure that your API upstream supports the listed ciphers.
For the supported ciphers, see [TLS Cipher Support on Flex Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Skipping validation disables outbound mTLS</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>skipValidation</code> is false</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate used in mTLS</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Flex Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS for a upstream service.

**Sample configuration for adding outbound TLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: tls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: true
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

**Sample configuration for adding outbound mTLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: false
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
```

## TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-tls-config)

- [Configuring TLS Context for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/1.9/policies-included-tls)

<!-- document id=b4d29ee1f94211def4b879d3030e760c5738ac51946d54be76ac329776e2da1a url=/mulesoft/current/en-us/gateway/latest/policies-included-tls-outbound.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: tls, mtls, transport layer security, outbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Outbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Outbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables two-way authentication between the API proxy and an upstream service</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni version available</strong></p></td><td><div><div><p>v1.4.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-outbound-release-notes">Transport Layer Security (TLS) - Outbound</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Omni Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tls-config).

## Summary

Omni Gateway supports outbound Transport Layer Security (TLS) and outbound mutual authentication TLS
(mTLS) in Local Mode.

By default, Omni Gateway supports outbound TLS to communicate with upstream services that require a
secure communication channel. For default outbound communication, Omni Gateway uses only TLS 1.2. To
find the default TLS 1.2 ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). To find
the ciphers, see [Omni Gateway Supported Ciphers](#supported-ciphers). Applying a TLS context to an
upstream overrides the default TLS context for that upstream. Because the default ciphers may change
for later Omni Gateway versions, you can apply a TLS context to an upstream to ensure it remains the
same.

To apply outbound TLS in Local Mode, use the
[Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tls-config) tutorial and refer to the
following configuration files in this documentation.

You can configure an outbound TLS context to enable authentication between an API instance and an
upstream service by binding the TLS policy to the upstream service.

Unlike inbound TLS, it is not suggested to apply the same outbound TLS context to all API instances
in your Omni Gateway because your API upstream services might come from different providers.
Therefore, no configuration example for outbound TLS on all instances is provided.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each
individual upstream service.

> [!NOTE] TLS policies do not support policy ordering.

> [!NOTE] Upstream certificates must include the Subject Alternative Name (SAN) extension. The
> Common Name (CN) field is deprecated.
>
> Omni Gateway supports the SAN extension of type `dNSName`.

> [!NOTE] The Authority Information Access (AIA) certificate extension is not supported when
> configuring outbound TLS contexts.

## Configuring Policy Parameters

To enable outbound TLS between an API instance and an upstream service when using Omni Gateway as
your runtime, you must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

\- policyRef: name: tls-outbound config: skipValidation: <boolean> // REQUIRED certificate: //
OPTIONAL key: <string> // OPTIONAL crt: <string> // OPTIONAL alpn: <array> // OPTIONAL minversion:
<string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values
to your TLS context.

When configuring the `ciphers` parameter, ensure that your API upstream supports the listed ciphers.
For the supported ciphers, see [TLS Cipher Support on Omni Gateway](#local-support).

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>skipValidation</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>If true, the upstream certificate is not validated.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>skipValidation</code> is false</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the upstream server certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The client certificate to present for mTLS. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format).</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS for a upstream service.

**Sample configuration for adding outbound TLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: tls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: true
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

This example uses the default values for `alpn`, `minversion`, `maxversion`, and `ciphers`.

**Sample configuration for adding outbound mTLS context for a specific upstream service:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: false
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
```

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 to TLS 1.3, and you can also customize some of
the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default
ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t
support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers
besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default
ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you
do not support those ciphers. If you wish to only support the default ciphers, you can leave the
cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

> [!IMPORTANT] For outbound TLS Context, ensure that your upstream service supports the selected
> ciphers and versions.

### Omni Gateway Supported Ciphers

Omni Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-tls-config)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

<!-- document id=c42c0cc4e46e193073dc1ddd8fb4e799a341d96536352b3a83be8cd712ad3b2e url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-docker.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Docker Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `docker` command:

- [Docker Is Not Started](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

## Docker Is Not Started

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

## Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add a Flex Gateway**
  page for Kubernetes and rerun the registration command.

## See Also

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-requests)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-admin-api)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=bfc008fdf161d5df8cb014a2db7268f93adda5939468cca7e6a14fadfca31c37 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-docker.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Docker Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `docker` command:

- [Docker Is Not Started](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

## Docker Is Not Started

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

## Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add an Omni
  Gateway** page for Kubernetes and rerun the registration command.

## See Also

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.13/troubleshoot-requests)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.13/troubleshoot-admin-api)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=c5dd35fe8a4d5b0264e748892b017fdebdae3a2e57c4073b3e5f61f47a60810f url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-docker.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Docker Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `docker` command:

- [Docker Is Not Started](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

## Docker Is Not Started

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

## Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add a Flex Gateway**
  page for Kubernetes and rerun the registration command.

## See Also

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-requests)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-admin-api)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=892f4a8d313aae3b6a2af5c2495fbc97d49550d87cf71b7e9d4d0d3550d58290 url=/mulesoft/current/en-us/gateway/latest/troubleshoot-docker.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Docker Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `docker` command:

- [Docker Is Not Started](#daemon-bad-response)

- [Reg Facade Error (400 Bad Request)](#bad-request)

## Docker Is Not Started

If Docker is not started, a `docker` command returns an error message similar to the following ones:

- Error response from daemon: Bad response from Docker engine

- ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon
  running?

If you get this error, start Docker.

## Reg Facade Error (400 Bad Request)

The following error can occur when you use `docker run` to register your gateway:

\[flexctl\]\[error\] reg facade call returned error response: HTTP/1.1 400 Bad Request

The reason for this error is available within the error message. Common causes include:

- `an active target with the same name already exists in this organization and environment`

  To avoid this issue, provide a _unique name_ for your gateway when running the registration
  command. Note that you _cannot reuse the same name_ even if a previous registration with that name
  was successful. When this error occurs, the command generates an _empty_ `registration.yaml`,
  which prevents re-registration _and_ produces an error when you try to use the file when deploying
  the gateway to your cluster.

- `no valid registration token was found`

  To avoid this issue, generate a new token for the command by refreshing the **Add an Omni
  Gateway** page for Kubernetes and rerun the registration command.

## See Also

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/latest/troubleshoot-requests)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/latest/troubleshoot-admin-api)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=db0f88a4848882411504e095af7b30360cae3566f165541c4e4fa0ca3884cdc1 url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When you perform Anypoint Flex Gateway tasks, you might encounter issues or receive error messages.
These topics help you resolve these issues:

## Troubleshooting Managed Flex Gateway

- [Troubleshooting Managed Flex Gateway Creation](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-managed-creation)

- [Troubleshooting Managed Gateway Maintenance](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-managed-maintenance)

## Troubleshooting Self-Managed Flex Gateway

- [Troubleshooting Self-Managed Gateway with Debug Logs](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-debug-logs)

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-reg)

- [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-linux-permissions)

- [Troubleshooting Platform Connections](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-platform-connection)

- [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-logging)

- [Troubleshooting Linux Services](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-linux-services)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-admin-api)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-requests)

- [Troubleshooting Docker Command Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-docker)

- [Troubleshooting Helm Command Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-helm)

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=3ca0f18fe0ebfe97c7aa3fcf325fe32494f8514385c7d7fcae410a52d73e6659 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When you perform Anypoint Flex Gateway tasks, you might encounter issues or receive error messages.
These topics help you resolve these issues:

## Troubleshooting Managed Flex Gateway

- [Troubleshooting Managed Flex Gateway Creation](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-managed-creation)

- [Troubleshooting Managed Gateway Maintenance](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-managed-maintenance)

## Troubleshooting Self-Managed Flex Gateway

- [Troubleshooting Self-Managed Gateway with Debug Logs](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-debug-logs)

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-reg)

- [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-linux-permissions)

- [Troubleshooting Platform Connections](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-platform-connection)

- [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-logging)

- [Troubleshooting Linux Services](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-linux-services)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-admin-api)

- [Troubleshooting SOAP APIs](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-soap-apis)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-requests)

- [Troubleshooting Docker Command Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-docker)

- [Troubleshooting Helm Command Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-helm)

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=55b5d1890af22b8181af3a14e226c726ce1e534a2e11ad70146e28f1c93e7d9c url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-helm.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Helm Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

## Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Flex Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See
[Register Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-getting-started#register-flex) for an example of the
registration command.

## Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

## Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Flex Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

## Failed to Install CRD

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

## See Also

- [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-getting-started)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=77dc42b8108802ddfabd25fac34fa2c3d8f5016edb7425ad4873d1f7a6dfcb13 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-helm.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Helm Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

## Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Omni Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See
[Register Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-k8-getting-started#register-flex) for an example of the registration
command.

## Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

## Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Omni Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

## Failed to Install CRD

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

## See Also

- [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-k8-getting-started)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=7a5521b12c8ec4d2117437d027c8c04d0197d6b5b170664c31e4e404bd31f445 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-helm.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Helm Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

## Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Flex Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See
[Register Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-getting-started#register-flex) for an example of the
registration command.

## Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

## Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Flex Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

## Failed to Install CRD

When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Flex Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

## See Also

- [Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-getting-started)

- [Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=63cbbc4b70fb267a1893f096bc599c9ab0d672541f3e0ee18334b429a1002b1b url=/mulesoft/current/en-us/gateway/latest/troubleshoot-helm.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Helm Command Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot errors returned by a `helm` command for Kubernetes and OpenShift clusters:

- [Upgrade Failed: Execution Error](#troubleshoot-helm-yaml-empty)

- [Kubernetes Cluster Unreachable](#troubleshoot-helm-cluster-unreachable)

- [Upgrade Failed: Timed Out](#troubleshoot-helm-upgrade-failed)

- [Failed to Install CRD](#troubleshoot-helm-openshift-rbac)

## Upgrade Failed: Execution Error

If the `registration.yaml` file is invalid when you pass it to the Helm command during deployment of
Omni Gateway, the following error results:

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

When this error occurs, make sure that the `registration.yaml` file is not empty. If the file is
empty, reregister your gateway with a new, unique name to generate a new `registration.yaml` and
rerun the procedures that follow the registration step. See
[Register Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-k8-getting-started#register-flex) for an example of the registration
command.

## Upgrade Failed: Timed Out

Some issues can cause the Helm upgrade command to hang for up to 5 minutes (due to the `--wait` flag
in the command) before producing the following timeout error:

Error: UPGRADE FAILED: timed out waiting for the condition

This error typically means that your cluster configuration is incorrect or that your cluster
configuration tool does not support this process. One potential cause is the failure to generate a
`Service` resource of the `LoadBalancer` type. You can troubleshoot further by running the following
commands:

- ```kubectl
  kubectl -n gateway describe deployment
  ```

- ```kubectl
  kubectl -n gateway describe service
  ```

## Kubernetes Cluster Unreachable

If your Kubernetes cluster is not running when you attempt to deploy Omni Gateway using `helm`, the
following error might occur:

Error: Kubernetes cluster unreachable: the server could not find the requested resource

Start the service that runs your cluster.

Check that your Kubernetes cluster host is running your cluster, for example:

```kubectl
kubectl cluster-info
```

- If the cluster is running, the command returns a result similar to this one:

  Kubernetes control plane is running at https://34.30.50.119 GLBCDefaultBackend is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
  KubeDNS is running at
  https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is
  running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

- If the cluster is not up, the command can return a result similar to this one:

  To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. error: the server
  doesn't have a resource type "services"

## Failed to Install CRD

When deploying Omni Gateway to a Kubernetes cluster that enables role-based access control (RBAC),
you must have cluster-level permissions to permit installation of custom resource definitions (CRDs)
used by Omni Gateway. In OpenShift, the `cluster-admin` role provides this level of access.

Without the required access, you receive an error similar to the following one:

Error: failed to install CRD crds/apiinstance.yaml: customresourcedefinitions.apiextensions.k8s.io
is forbidden: User "user1" cannot create resource "customresourcedefinitions" in API group
"apiextensions.k8s.io" at the cluster scope

## See Also

- [Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-k8-getting-started)

- [Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=12e28f70cf8fa1ae112f29ca9b78c316f6a7d072c165eb9d707631f22f87d62e url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-linux-permissions.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Linux Permissions

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To help limit access to information about a Flex Gateway, the following `flexctl` commands can be
executed on Linux deployments only by the root user and by users in the `flex` user group:

- `flexctl dump`

- `flexctl version`

- `flexctl check connections`

- `flexctl probe`

- `flexctl registration inspect` (when executed without the `--file` flag)

There are two options to execute these commands:

- [Add the User to the Flex User Group](#add-user-to-flex-group)

- [Run as the Root User](#run-as-root-user)

## Add the User to the Flex User Group

Adding a user to the `flex` user group is a permanent solution and requires no action after the user
is added. Execute the following command to add the current user to the `flex` user group:

```ssh
sudo usermod -a -G flex $USER
```

After running the command, the user must log in to the VM again to begin using the `flexctl`
commands.

## Run as the Root User

Executing the `sudo` command with your `flexctl` command is the quickest way to access Flex Gateway
information. However, you must execute the `sudo` command every time you run a `flexctl` command if
the user is not part of the `flex` user group:

```ssh
sudo flexctl <command>
```

When the `sudo flexctl dump` command is executed, the root user is the owner of the created dump
files. If the current user is not the root user, the user cannot view the dumped files. To view the
files, execute the following command to change the owner of the files:

```ssh
sudo chown $USER *.json
```

Files in the `conf.d` directory must have `644` permissions, allowing the owner to read and write,
and the group and others to read.

## See Also

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-admin-api)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=f3b11218ca40da662e7a23cc0107ccf6ec317f99bc5a87e291ec434618646df0 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-linux-permissions.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Linux Permissions

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To help limit access to information about an Omni Gateway, the following `flexctl` commands can be
executed on Linux deployments only by the root user and by users in the `flex` user group:

- `flexctl dump`

- `flexctl version`

- `flexctl check connections`

- `flexctl probe`

- `flexctl registration inspect` (when executed without the `--file` flag)

There are two options to execute these commands:

- [Add the User to the flex User Group](#add-user-to-flex-group)

- [Run as the Root User](#run-as-root-user)

## Add the User to the flex User Group

Adding a user to the `flex` user group is a permanent solution and requires no action after the user
is added. Execute the following command to add the current user to the `flex` user group:

```ssh
sudo usermod -a -G flex $USER
```

After running the command, the user must log in to the VM again to begin using the `flexctl`
commands.

## Run as the Root User

Executing the `sudo` command with your `flexctl` command is the quickest way to access Omni Gateway
information. However, you must execute the `sudo` command every time you run a `flexctl` command if
the user is not part of the `flex` user group:

```ssh
sudo flexctl <command>
```

When the `sudo flexctl dump` command is executed, the root user is the owner of the created dump
files. If the current user is not the root user, the user cannot view the dumped files. To view the
files, execute the following command to change the owner of the files:

```ssh
sudo chown $USER *.json
```

Files in the `conf.d` directory must have `644` permissions, allowing the owner to read and write,
and the group and others to read.

## See Also

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.13/troubleshoot-admin-api)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=55f21f8cb1d7c69a0d53b897b2ed38c91a761509cb863e7388b7bb3452dd2dca url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-linux-permissions.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Linux Permissions

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To help limit access to information about a Flex Gateway, the following `flexctl` commands can be
executed on Linux deployments only by the root user and by users in the `flex` user group:

- `flexctl dump`

- `flexctl version`

- `flexctl check connections`

- `flexctl probe`

- `flexctl registration inspect` (when executed without the `--file` flag)

There are two options to execute these commands:

- [Add the User to the Flex User Group](#add-user-to-flex-group)

- [Run as the Root User](#run-as-root-user)

## Add the User to the Flex User Group

Adding a user to the `flex` user group is a permanent solution and requires no action after the user
is added. Execute the following command to add the current user to the `flex` user group:

```ssh
sudo usermod -a -G flex $USER
```

After running the command, the user must log in to the VM again to begin using the `flexctl`
commands.

## Run as the Root User

Executing the `sudo` command with your `flexctl` command is the quickest way to access Flex Gateway
information. However, you must execute the `sudo` command every time you run a `flexctl` command if
the user is not part of the `flex` user group:

```ssh
sudo flexctl <command>
```

When the `sudo flexctl dump` command is executed, the root user is the owner of the created dump
files. If the current user is not the root user, the user cannot view the dumped files. To view the
files, execute the following command to change the owner of the files:

```ssh
sudo chown $USER *.json
```

## See Also

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-admin-api)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=ccf8127c1bad3201b1a1865566119f393bcd33b27e21d194d7e1fa02d30d6668 url=/mulesoft/current/en-us/gateway/latest/troubleshoot-linux-permissions.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Linux Permissions

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To help limit access to information about an Omni Gateway, the following `flexctl` commands can be
executed on Linux deployments only by the root user and by users in the `flex` user group:

- `flexctl dump`

- `flexctl version`

- `flexctl check connections`

- `flexctl probe`

- `flexctl registration inspect` (when executed without the `--file` flag)

There are two options to execute these commands:

- [Add the User to the flex User Group](#add-user-to-flex-group)

- [Run as the Root User](#run-as-root-user)

## Add the User to the flex User Group

Adding a user to the `flex` user group is a permanent solution and requires no action after the user
is added. Execute the following command to add the current user to the `flex` user group:

```ssh
sudo usermod -a -G flex $USER
```

After running the command, the user must log in to the VM again to begin using the `flexctl`
commands.

## Run as the Root User

Executing the `sudo` command with your `flexctl` command is the quickest way to access Omni Gateway
information. However, you must execute the `sudo` command every time you run a `flexctl` command if
the user is not part of the `flex` user group:

```ssh
sudo flexctl <command>
```

When the `sudo flexctl dump` command is executed, the root user is the owner of the created dump
file. If the current user is not the root user, the user cannot view the dump file. To view the
file, execute the following command to change the owner of the file:

```ssh
sudo chown $USER dump.zip
```

Files in the `conf.d` directory must have `644` permissions, allowing the owner to read and write,
and the group and others to read.

## See Also

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/latest/troubleshoot-admin-api)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=5f98a7ea5e20a433f28699ff5523736ee3ff2c8e86ac5a4ca59b5ee0b10606af url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-linux-services.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Linux Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following topics provide possible causes for service issues and describe how to troubleshoot:

- [Flex Gateway Service Failed to Run](#flex-gateway-service-failed-to-run)

- [Other Services Failed to Run](#other-services-failed-to-run)

## Flex Gateway Service Failed to Run

The `flex-gateway.service` status displays `failed` after running the
`systemctl list-units flex-gateway*` command.

### Diagnose

To diagnose the service failure, run the following command:

```ssh
journalctl -u flex-gateway
```

#### Error 1: “Panic: could not read platform configuration”

If the output of the `journalctl` command includes this line:

```ssh
flex-agent[3253]: panic: could not read platform configuration: open : no such file or directory
```

The problem can be resolved by running `chmod` on the files created during registration.

## Other Services Failed to Run

If your error does not appear, attempt to restart Flex Gateway:

```ssh
sudo ldconfig
sudo systemctl restart flex-gateway
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=f2f330db4e0631b367fecb4c74b1a3430571c2e59234fef206ce8c566941e645 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-linux-services.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Linux Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following topics provide possible causes for service issues and describe how to troubleshoot:

- [Omni Gateway Service Failed to Run](#flex-gateway-service-failed-to-run)

- [Other Services Failed to Run](#other-services-failed-to-run)

## Omni Gateway Service Failed to Run

The `flex-gateway.service` status displays `failed` after running the
`systemctl list-units flex-gateway*` command.

### Diagnose

To diagnose the service failure, run the following command:

```ssh
journalctl -u flex-gateway
```

#### Error 1: “Panic: could not read platform configuration”

If the output of the `journalctl` command includes this line:

```ssh
flex-agent[3253]: panic: could not read platform configuration: open : no such file or directory
```

The problem can be resolved by running `chmod` on the files created during registration.

## Other Services Failed to Run

If your error does not appear, attempt to restart Omni Gateway:

```ssh
sudo ldconfig
sudo systemctl restart flex-gateway
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=30e4670ec8e29bd72007e1bdf421034d22a26976ae2c724b08dac5fc2ffc1415 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-linux-services.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Linux Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following topics provide possible causes for service issues and describe how to troubleshoot:

- [Flex Gateway Service Failed to Run](#flex-gateway-service-failed-to-run)

- [Other Services Failed to Run](#other-services-failed-to-run)

## Flex Gateway Service Failed to Run

The `flex-gateway.service` status displays `failed` after running the
`systemctl list-units flex-gateway*` command.

### Diagnose

To diagnose the service failure, run the following command:

```ssh
journalctl -u flex-gateway
```

#### Error 1: “Panic: could not read platform configuration”

If the output of the `journalctl` command includes this line:

```ssh
flex-agent[3253]: panic: could not read platform configuration: open : no such file or directory
```

The problem can be resolved by running `chmod` on the files created during registration.

## Other Services Failed to Run

If your error does not appear, attempt to restart Flex Gateway:

```ssh
sudo ldconfig
sudo systemctl restart flex-gateway
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=364df52828149e5595a3b24ba2f83963503aeebcc9425fe48b9d6d5ed34f510e url=/mulesoft/current/en-us/gateway/latest/troubleshoot-linux-services.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Linux Services

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The following topics provide possible causes for service issues and describe how to troubleshoot:

- [Omni Gateway Service Failed to Run](#flex-gateway-service-failed-to-run)

- [Other Services Failed to Run](#other-services-failed-to-run)

## Omni Gateway Service Failed to Run

The `flex-gateway.service` status displays `failed` after running the
`systemctl list-units flex-gateway*` command.

### Diagnose

To diagnose the service failure, run the following command:

```ssh
journalctl -u flex-gateway
```

#### Error 1: “Panic: could not read platform configuration”

If the output of the `journalctl` command includes this line:

```ssh
flex-agent[3253]: panic: could not read platform configuration: open : no such file or directory
```

The problem can be resolved by running `chmod` on the files created during registration.

## Other Services Failed to Run

If your error does not appear, attempt to restart Omni Gateway:

```ssh
sudo ldconfig
sudo systemctl restart flex-gateway
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=dc81be079e79cf9ebaa67565bd9a36e2d3736250d82a700a4d26f2ea3819e723 url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-managed-creation.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Managed Flex Gateway Creation

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When creating and deploying a Managed Flex Gateway instance, you might encounter issues. Check these
topics for possible causes and solutions.

- [Add Managed Flex Gateway Button is Missing](#add-button-missing)

- [Add Managed Flex Gateway Button is Disabled](#add-button-disabled)

- [Private Space Not Available](#private-space)

## Add Managed Flex Gateway Button is Missing

The **Add Managed Flex Gateway** button in Runtime Manager might be missing because the selected
business group does not have Managed Flex Gateway resources. Instead you see a "Start protecting
your APIs with Managed Flex Gateways" message and a **Create a Self-Managed Flex Gateway** button.

Check Your Business Group Managed Flex Gateway Resources

1.  Navigate to **Access Management > Subscription > Runtime Manage Subscription**. If your
    subscription tier doesn’t include **Small Managed Flex Gateways** and **Large Managed Flex
    Gateways** resources, contact your MuleSoft representative for more information.

2.  If your business group shows quantity **0/0 in use** or shows **Reassigned** for **Small Managed
    Flex Gateways** or **Large Managed Flex Gateways**, try redistributing Managed Flex Gateway
    resources from one organization or business group to your selected business group. See
    [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Add Managed Flex Gateway Button is Disabled

The **Add Managed Flex Gateway** button in Runtime Manager might be disabled due to quota
limitations or insufficient permissions. This issue occurs if you reach the maximum number of
Managed Flex Gateways allowed for all sizes in your organization or if you don’t have the required
_Manage Servers_ and _Read Servers_ Runtime Manager permissions .

Check Managed Flex Gateway quotas for your organization

1.  In Anypoint Platform, go to **Access Management**.

2.  Click **Runtime Manager** in **Subscription** section of the side navigation panel.

3.  Review the Managed Gateway quotas to determine if the quota has been exhausted for all Managed
    Flex Gateway sizes.

To deploy more Managed Flex Gateways, delete existing gateways or upgrade to a subscription plan
with a higher quota.

Verify your permissions

In Access Management, ensure that you have the required _Manage Servers_ and _Read Servers_ Runtime
Manager permissions.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions).

## Private Space Not Available

When creating a new Managed Flex Gateway, if you don’t see the desired Private Space in the
**Deployment Target** list, you might not have the necessary permissions for that Private Space.

Verify the Private Space permissions

1.  In Runtime Manager, access the details of the Private Space you are trying to use.

2.  Navigate to the **Environments** tab.

3.  Confirm that the target organization and environment are within the allowed environments for
    that private space.

If necessary, update the Private Space Environments configuration to include the target organization
and environment:

1.  Modify the Private Space **Environments** configuration to include the target organization and
    environment.

2.  Wait a few minutes for the changes to propagate and be reflected in the **Deployment Target**
    list.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=a64fd2d74446090c034d754a597e47e9cd0b88aa62ddfef64efe946ad0e92fdd url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-managed-creation.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Managed Flex Gateway Creation

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When creating and deploying a Managed Flex Gateway instance, you might encounter issues. Check these
topics for possible causes and solutions.

- [Add Managed Flex Gateway Button is Missing](#add-button-missing)

- [Add Managed Flex Gateway Button is Disabled](#add-button-disabled)

- [Private Space Not Available](#private-space)

## Add Managed Flex Gateway Button is Missing

The **Add Managed Flex Gateway** button in Runtime Manager might be missing because the selected
business group does not have Managed Flex Gateway resources. Instead you see a "Start protecting
your APIs with Managed Flex Gateways" message and a **Create a Self-Managed Flex Gateway** button.

Check Your Business Group Managed Flex Gateway Resources

1.  Navigate to **Access Management > Subscription > Runtime Manage Subscription**. If your
    subscription tier doesn’t include **Small Managed Flex Gateways** and **Large Managed Flex
    Gateways** resources, contact your MuleSoft representative for more information.

2.  If your business group shows quantity **0/0 in use** or shows **Reassigned** for **Small Managed
    Flex Gateways** or **Large Managed Flex Gateways**, try redistributing Managed Flex Gateway
    resources from one organization or business group to your selected business group. See
    [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Add Managed Flex Gateway Button is Disabled

The **Add Managed Flex Gateway** button in Runtime Manager might be disabled due to quota
limitations or insufficient permissions. This issue occurs if you reach the maximum number of
Managed Flex Gateways allowed for all sizes in your organization or if you don’t have the required
_Manage Servers_ and _Read Servers_ Runtime Manager permissions .

Check Managed Flex Gateway quotas for your organization

1.  In Anypoint Platform, go to **Access Management**.

2.  Click **Runtime Manager** in **Subscription** section of the side navigation panel.

3.  Review the Managed Gateway quotas to determine if the quota has been exhausted for all Managed
    Flex Gateway sizes.

To deploy more Managed Flex Gateways, delete existing gateways or upgrade to a subscription plan
with a higher quota.

Verify your permissions

In Access Management, ensure that you have the required _Manage Servers_ and _Read Servers_ Runtime
Manager permissions.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions).

## Private Space Not Available

When creating a new Managed Flex Gateway, if you don’t see the desired Private Space in the
**Deployment Target** list, you might not have the necessary permissions for that Private Space.

Verify the Private Space permissions

1.  In Runtime Manager, access the details of the Private Space you are trying to use.

2.  Navigate to the **Environments** tab.

3.  Confirm that the target organization and environment are within the allowed environments for
    that private space.

If necessary, update the Private Space Environments configuration to include the target organization
and environment:

1.  Modify the Private Space **Environments** configuration to include the target organization and
    environment.

2.  Wait a few minutes for the changes to propagate and be reflected in the **Deployment Target**
    list.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=5c173e0e2428d02e7aa80ec2f5549536a09f129d549d20ac9ca3228e2da81d46 url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-managed-maintenance.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Managed Gateway Maintenance

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When viewing or maintaining Anypoint Managed Flex Gateway instances, you might encounter issues.
Check these topics for possible causes and solutions.

- [Missing Gateway Metrics](#gateway-metrics-not-showing)

- [Gateway Properties Not Editable](#cant-change-gateway-properties)

- [Timeout While Waiting for Update](#timeout-while-waiting-for-update)

- [Gateway is Missing or Disabled](#gateway-missing-disabled)

- [API Path Conflict](#same-path-error)

## Missing Gateway Metrics

In Runtime Manager, if you can’t see metrics for your gateway from the Managed Flex Gateway
dashboard, verify that you have the _Usage Viewer_ permission.

Verify your permissions

Check your assigned roles and permissions in Access Management to verify that you have the required
_Usage Viewer_ Runtime Manager permission.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) .

## Can’t Change Gateway Properties

You can’t edit some Managed Flex Gateway properties, such as **Gateway Name**, **Deployment
Target**, and **Flow plans**, after the gateway instance is created. To change these properties, you
must delete and recreate your Managed Flex Gateway with the desired values.

## Timeout While Waiting for Update

If your Managed Flex Gateway update or deletion is stalled, refresh the status and check again in a
few minutes. Delays might happen when the Anypoint Platform is handling a lot of traffic.

## Gateway is Missing or Disabled in API Manager

When adding an API instance to a gateway, if you don’t find your Managed Flex Gateway in the API
Manager **Select a gateway** list or the Managed Flex Gateway is disabled, view the gateway status
in Runtime Manager to ensure the gateway is running. If the gateway status isn’t **Running**, fix
the probelm from Runtime Manager. If the gateway status is **Running** but still unavailable in API
Manager, there might be a cluster issue, and you should contact MuleSoft Support for assistance.

## API Path Conflict

When an API to a Managed Flex Gateway, if you see the **This path conflicts with another API** error
in API Manager, you must choose a different base path. Each API instance in a Flex Gateway must be
unique within the gateway. To fix this problem, change the API path to a unique value or edit the
path of the other API instance. Click **API** in the error message to view and edit the API instance
with the conflicting path.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=3f2788ebdf558e3d9328964d369aac49ddecd17c2caff2fcdc095035dd4f1449 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-managed-maintenance.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Managed Gateway Maintenance

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When viewing or maintaining Anypoint Managed Omni Gateway instances, you might encounter issues.
Check these topics for possible causes and solutions.

- [Missing Gateway Metrics](#gateway-metrics-not-showing)

- [Gateway Properties Not Editable](#cant-change-gateway-properties)

- [Timeout While Waiting for Update](#timeout-while-waiting-for-update)

- [Gateway is Missing or Disabled](#gateway-missing-disabled)

- [API Path Conflict](#same-path-error)

## Missing Gateway Metrics

In Runtime Manager, if you can’t see metrics for your gateway from the Managed Omni Gateway
dashboard, verify that you have the _Usage Viewer_ permission.

Verify your permissions

Check your assigned roles and permissions in Access Management to verify that you have the required
_Usage Viewer_ Runtime Manager permission.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) .

## Can’t Change Gateway Properties

You can’t edit some Managed Omni Gateway properties, such as **Gateway Name**, **Deployment
Target**, and **Flow plans**, after the gateway instance is created. To change these properties, you
must delete and recreate your Managed Omni Gateway with the desired values.

## Timeout While Waiting for Update

If your Managed Omni Gateway update or deletion is stalled, refresh the status and check again in a
few minutes. Delays might happen when the Anypoint Platform is handling a lot of traffic.

## Gateway is Missing or Disabled in API Manager

When adding an API instance to a gateway, if you don’t find your Managed Omni Gateway in the API
Manager **Select a gateway** list or the Managed Omni Gateway is disabled, view the gateway status
in Runtime Manager to ensure the gateway is running. If the gateway status isn’t **Running**, fix
the probelm from Runtime Manager. If the gateway status is **Running** but still unavailable in API
Manager, there might be a cluster issue, and you should contact MuleSoft Support for assistance.

## API Path Conflict

When an API to a Managed Omni Gateway, if you see the **This path conflicts with another API** error
in API Manager, you must choose a different base path. Each API instance in an Omni Gateway must be
unique within the gateway. To fix this problem, change the API path to a unique value or edit the
path of the other API instance. Click **API** in the error message to view and edit the API instance
with the conflicting path.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=65657ca40eccbcc185ada02daacf14d9a99318c4daa82720fbf1a0e199f93c9f url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-managed-maintenance.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Managed Gateway Maintenance

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When viewing or maintaining Anypoint Managed Flex Gateway instances, you might encounter issues.
Check these topics for possible causes and solutions.

- [Missing Gateway Metrics](#gateway-metrics-not-showing)

- [Gateway Properties Not Editable](#cant-change-gateway-properties)

- [Timeout While Waiting for Update](#timeout-while-waiting-for-update)

- [Gateway is Missing or Disabled](#gateway-missing-disabled)

- [API Path Conflict](#same-path-error)

## Missing Gateway Metrics

In Runtime Manager, if you can’t see metrics for your gateway from the Managed Flex Gateway
dashboard, verify that you have the _Usage Viewer_ permission.

Verify your permissions

Check your assigned roles and permissions in Access Management to verify that you have the required
_Usage Viewer_ Runtime Manager permission.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) .

## Can’t Change Gateway Properties

You can’t edit some Managed Flex Gateway properties, such as **Gateway Name**, **Deployment
Target**, and **Flow plans**, after the gateway instance is created. To change these properties, you
must delete and recreate your Managed Flex Gateway with the desired values.

## Timeout While Waiting for Update

If your Managed Flex Gateway update or deletion is stalled, refresh the status and check again in a
few minutes. Delays might happen when the Anypoint Platform is handling a lot of traffic.

## Gateway is Missing or Disabled in API Manager

When adding an API instance to a gateway, if you don’t find your Managed Flex Gateway in the API
Manager **Select a gateway** list or the Managed Flex Gateway is disabled, view the gateway status
in Runtime Manager to ensure the gateway is running. If the gateway status isn’t **Running**, fix
the probelm from Runtime Manager. If the gateway status is **Running** but still unavailable in API
Manager, there might be a cluster issue, and you should contact MuleSoft Support for assistance.

## API Path Conflict

When an API to a Managed Flex Gateway, if you see the **This path conflicts with another API** error
in API Manager, you must choose a different base path. Each API instance in a Flex Gateway must be
unique within the gateway. To fix this problem, change the API path to a unique value or edit the
path of the other API instance. Click **API** in the error message to view and edit the API instance
with the conflicting path.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=1b399e22438a19350b5bda0fd145cb5cf3977c161af04213509f7422c768cb5c url=/mulesoft/current/en-us/gateway/latest/troubleshoot-managed-maintenance.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Managed Gateway Maintenance

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When viewing or maintaining Anypoint Managed Omni Gateway instances, you might encounter issues.
Check these topics for possible causes and solutions.

- [Missing Gateway Metrics](#gateway-metrics-not-showing)

- [Gateway Properties Not Editable](#cant-change-gateway-properties)

- [Timeout While Waiting for Update](#timeout-while-waiting-for-update)

- [Gateway is Missing or Disabled](#gateway-missing-disabled)

- [API Path Conflict](#same-path-error)

## Missing Gateway Metrics

In Runtime Manager, if you can’t see metrics for your gateway from the Managed Omni Gateway
dashboard, verify that you have the _Usage Viewer_ permission.

Verify your permissions

Check your assigned roles and permissions in Access Management to verify that you have the required
_Usage Viewer_ Runtime Manager permission.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions) .

## Can’t Change Gateway Properties

You can’t edit some Managed Omni Gateway properties, such as **Gateway Name**, **Deployment
Target**, and **Flow plans**, after the gateway instance is created. To change these properties, you
must delete and recreate your Managed Omni Gateway with the desired values.

## Timeout While Waiting for Update

If your Managed Omni Gateway update or deletion is stalled, refresh the status and check again in a
few minutes. Delays might happen when the Anypoint Platform is handling a lot of traffic.

## Gateway is Missing or Disabled in API Manager

When adding an API instance to a gateway, if you don’t find your Managed Omni Gateway in the API
Manager **Select a gateway** list or the Managed Omni Gateway is disabled, view the gateway status
in Runtime Manager to ensure the gateway is running. If the gateway status isn’t **Running**, fix
the probelm from Runtime Manager. If the gateway status is **Running** but still unavailable in API
Manager, there might be a cluster issue, and you should contact MuleSoft Support for assistance.

## API Path Conflict

When an API to a Managed Omni Gateway, if you see the **This path conflicts with another API** error
in API Manager, you must choose a different base path. Each API instance in an Omni Gateway must be
unique within the gateway. To fix this problem, change the API path to a unique value or edit the
path of the other API instance. Click **API** in the error message to view and edit the API instance
with the conflicting path.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=8a49385acc946c62d52a8454af8f67a552f1d3219615e5987b63a3478fa34339 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-managed-creation.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Managed Omni Gateway Creation

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When creating and deploying a Managed Omni Gateway instance, you might encounter issues. Check these
topics for possible causes and solutions.

- [Add Managed Omni Gateway Button is Missing](#add-button-missing)

- [Add Managed Omni Gateway Button is Disabled](#add-button-disabled)

- [Private Space Not Available](#private-space)

## Add Managed Omni Gateway Button is Missing

The **Add Managed Omni Gateway** button in Runtime Manager might be missing because the selected
business group does not have Managed Omni Gateway resources. Instead you see a "Start protecting
your APIs with Managed Omni Gateways" message and a **Create a Self-Managed Omni Gateway** button.

Check Your Business Group Managed Omni Gateway Resources

1.  Navigate to **Access Management > Subscription > Runtime Manage Subscription**. If your
    subscription tier doesn’t include **Small Managed Omni Gateways** and **Large Managed Omni
    Gateways** resources, contact your MuleSoft representative for more information.

2.  If your business group shows quantity **0/0 in use** or shows **Reassigned** for **Small Managed
    Omni Gateways** or **Large Managed Omni Gateways**, try redistributing Managed Omni Gateway
    resources from one organization or business group to your selected business group. See
    [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Add Managed Omni Gateway Button is Disabled

The **Add Managed Omni Gateway** button in Runtime Manager might be disabled due to quota
limitations or insufficient permissions. This issue occurs if you reach the maximum number of
Managed Omni Gateways allowed for all sizes in your organization or if you don’t have the required
_Manage Servers_ and _Read Servers_ Runtime Manager permissions .

Check Managed Omni Gateway quotas for your organization

1.  In Anypoint Platform, go to **Access Management**.

2.  Click **Runtime Manager** in **Subscription** section of the side navigation panel.

3.  Review the Managed Gateway quotas to determine if the quota has been exhausted for all Managed
    Omni Gateway sizes.

To deploy more Managed Omni Gateways, delete existing gateways or upgrade to a subscription plan
with a higher quota.

Verify your permissions

In Access Management, ensure that you have the required _Manage Servers_ and _Read Servers_ Runtime
Manager permissions.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions).

## Private Space Not Available

When creating a new Managed Omni Gateway, if you don’t see the desired Private Space in the
**Deployment Target** list, you might not have the necessary permissions for that Private Space.

Verify the Private Space permissions

1.  In Runtime Manager, access the details of the Private Space you are trying to use.

2.  Navigate to the **Environments** tab.

3.  Confirm that the target organization and environment are within the allowed environments for
    that private space.

If necessary, update the Private Space Environments configuration to include the target organization
and environment:

1.  Modify the Private Space **Environments** configuration to include the target organization and
    environment.

2.  Wait a few minutes for the changes to propagate and be reflected in the **Deployment Target**
    list.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=2758a94ddbdc2f2307d0d008d967ed97cf409e84e980af466bec24eaa2642822 url=/mulesoft/current/en-us/gateway/latest/troubleshoot-managed-creation.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Managed Omni Gateway Creation

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When creating and deploying a Managed Omni Gateway instance, you might encounter issues. Check these
topics for possible causes and solutions.

- [Add Managed Omni Gateway Button is Missing](#add-button-missing)

- [Add Managed Omni Gateway Button is Disabled](#add-button-disabled)

- [Private Space Not Available](#private-space)

## Add Managed Omni Gateway Button is Missing

The **Add Managed Omni Gateway** button in Runtime Manager might be missing because the selected
business group does not have Managed Omni Gateway resources. Instead you see a "Start protecting
your APIs with Managed Omni Gateways" message and a **Create a Self-Managed Omni Gateway** button.

Check Your Business Group Managed Omni Gateway Resources

1.  Navigate to **Access Management > Subscription > Runtime Manage Subscription**. If your
    subscription tier doesn’t include **Small Managed Omni Gateways** and **Large Managed Omni
    Gateways** resources, contact your MuleSoft representative for more information.

2.  If your business group shows quantity **0/0 in use** or shows **Reassigned** for **Small Managed
    Omni Gateways** or **Large Managed Omni Gateways**, try redistributing Managed Omni Gateway
    resources from one organization or business group to your selected business group. See
    [Redistribute Resources Between Existing Business Groups](https://docs.mulesoft.com/access-management/business-groups#redistribute-resources).

## Add Managed Omni Gateway Button is Disabled

The **Add Managed Omni Gateway** button in Runtime Manager might be disabled due to quota
limitations or insufficient permissions. This issue occurs if you reach the maximum number of
Managed Omni Gateways allowed for all sizes in your organization or if you don’t have the required
_Manage Servers_ and _Read Servers_ Runtime Manager permissions .

Check Managed Omni Gateway quotas for your organization

1.  In Anypoint Platform, go to **Access Management**.

2.  Click **Runtime Manager** in **Subscription** section of the side navigation panel.

3.  Review the Managed Gateway quotas to determine if the quota has been exhausted for all Managed
    Omni Gateway sizes.

To deploy more Managed Omni Gateways, delete existing gateways or upgrade to a subscription plan
with a higher quota.

Verify your permissions

In Access Management, ensure that you have the required _Manage Servers_ and _Read Servers_ Runtime
Manager permissions.

Your Anypoint Platform Admin can add these permissions in Access Management. For more information,
see [Manage Team Permissions](https://docs.mulesoft.com/access-management/configure-teams#manage-team-permissions).

## Private Space Not Available

When creating a new Managed Omni Gateway, if you don’t see the desired Private Space in the
**Deployment Target** list, you might not have the necessary permissions for that Private Space.

Verify the Private Space permissions

1.  In Runtime Manager, access the details of the Private Space you are trying to use.

2.  Navigate to the **Environments** tab.

3.  Confirm that the target organization and environment are within the allowed environments for
    that private space.

If necessary, update the Private Space Environments configuration to include the target organization
and environment:

1.  Modify the Private Space **Environments** configuration to include the target organization and
    environment.

2.  Wait a few minutes for the changes to propagate and be reflected in the **Deployment Target**
    list.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=b11dbc2b48c32b8325ce17433ffb29fe082d465cff3afc0bc325e69295ad70db url=/mulesoft/current/en-us/gateway/1.13/troubleshoot.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When you perform Omni Gateway tasks, you might encounter issues or receive error messages. These
topics help you resolve these issues:

## Troubleshooting Managed Omni Gateway

- [Troubleshooting Managed Omni Gateway Creation](https://docs.mulesoft.com/gateway/1.13/troubleshoot-managed-creation)

- [Troubleshooting Managed Gateway Maintenance](https://docs.mulesoft.com/gateway/1.13/troubleshoot-managed-maintenance)

## Troubleshooting Self-Managed Omni Gateway

- [Troubleshooting Self-Managed Gateway with Debug Logs](https://docs.mulesoft.com/gateway/1.13/troubleshoot-debug-logs)

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-reg)

- [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/1.13/troubleshoot-linux-permissions)

- [Troubleshooting Platform Connections](https://docs.mulesoft.com/gateway/1.13/troubleshoot-platform-connection)

- [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-logging)

- [Troubleshooting Linux Services](https://docs.mulesoft.com/gateway/1.13/troubleshoot-linux-services)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/1.13/troubleshoot-admin-api)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.13/troubleshoot-requests)

- [Troubleshooting Docker Command Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-docker)

- [Troubleshooting Helm Command Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-helm)

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=b58511bc890c4053982c891762ed88f889512f79475d2a3fb3030c50eaedcbfb url=/mulesoft/current/en-us/gateway/latest/troubleshoot.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When you perform Omni Gateway tasks, you might encounter issues or receive error messages. These
topics help you resolve these issues:

## Troubleshooting Managed Omni Gateway

- [Troubleshooting Managed Omni Gateway Creation](https://docs.mulesoft.com/gateway/latest/troubleshoot-managed-creation)

- [Troubleshooting Managed Gateway Maintenance](https://docs.mulesoft.com/gateway/latest/troubleshoot-managed-maintenance)

## Troubleshooting Self-Managed Omni Gateway

- [Troubleshooting Self-Managed Gateway with Debug Logs](https://docs.mulesoft.com/gateway/latest/troubleshoot-debug-logs)

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-reg)

- [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/latest/troubleshoot-linux-permissions)

- [Troubleshooting Platform Connections](https://docs.mulesoft.com/gateway/latest/troubleshoot-platform-connection)

- [Troubleshooting Self-Managed Gateway Logging Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-logging)

- [Troubleshooting Linux Services](https://docs.mulesoft.com/gateway/latest/troubleshoot-linux-services)

- [Troubleshooting with the CLI](https://docs.mulesoft.com/gateway/latest/troubleshoot-admin-api)

- [Resetting the Control Node Cache with the CLI](https://docs.mulesoft.com/gateway/latest/troubleshoot-reset-cache)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/latest/troubleshoot-requests)

- [Troubleshooting Docker Command Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-docker)

- [Troubleshooting Helm Command Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-helm)

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=84f06d0e229f67e407bfc4dbe04fc32324a20f624a47c8053e6294b118016d0b url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-platform-connection.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Platform Connections

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring Flex Gateway, it is possible for the Flex Replica’s `registration.yaml` to be
absent or for the replica to lose its connection to Anypoint Platform.

To troubleshoot whether a registration file is present and whether Flex Gateway can make platform
connections, use the following command:

```ssh
flexctl check connections
```

The `flexctl check connections` command first ensures that a `registration.yaml` file is present.
Then it checks whether the replica can connect to the URLs defined in the registration file. If the
`flexctl check connections` command is successful, it returns the following `info` message:

$ flexctl check connections \[flexctl\]\[info\] Connection to platform endpoints successful.

## No Registration File Found

If the `registration.yaml` file isn’t found, Flex Gateway returns the following error message:

$ flexctl check connections Error: no registration config

To troubleshoot an absent registration file, check your Flex Replica configuration folder. To learn
more about registering a Flex Gateway, see following section for your relevant mode:

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-reg-run)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-reg-run)

## Failed Connection

There are multiple reasons why Flex Gateway might experience connection issues, such as an error in
the gateway’s environment or a network issue. How you troubleshoot your error depends on the error
returned.

If Flex Gateway can’t connect to a specific URL, it returns an error message that includes the
unreachable URL and the error message returned from the connection attempt. The following error
message is an example of an error returned due to no internet connection:

$ flexctl check connections Error: failed connecting to https://anypoint.mulesoft.com/: dial tcp
52.22.227.22:443: connect: network is unreachable

## See Also

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-reg)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-requests)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=1086786ac259c388a6aa113bdff6e6f52ec298c0ca6deb61695bd12b80c9fb62 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-platform-connection.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Platform Connections

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring Omni Gateway, it is possible for the Omni Replica’s `registration.yaml` to be
absent or for the replica to lose its connection to Anypoint Platform.

To troubleshoot whether a registration file is present and whether Omni Gateway can make platform
connections, use the following command:

```ssh
flexctl check connections
```

The `flexctl check connections` command first ensures that a `registration.yaml` file is present.
Then it checks whether the replica can connect to the URLs defined in the registration file. If the
`flexctl check connections` command is successful, it returns the following `info` message:

$ flexctl check connections \[flexctl\]\[info\] Connection to platform endpoints successful.

## No Registration File Found

If the `registration.yaml` file isn’t found, Omni Gateway returns the following error message:

$ flexctl check connections Error: no registration config

To troubleshoot an absent registration file, check your Omni Replica configuration folder. To learn
more about registering an Omni Gateway, see following section for your relevant mode:

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-reg-run)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-reg-run)

## Failed Connection

There are multiple reasons why Omni Gateway might experience connection issues, such as an error in
the gateway’s environment or a network issue. How you troubleshoot your error depends on the error
returned.

If Omni Gateway can’t connect to a specific URL, it returns an error message that includes the
unreachable URL and the error message returned from the connection attempt. The following error
message is an example of an error returned due to no internet connection:

$ flexctl check connections Error: failed connecting to https://anypoint.mulesoft.com/: dial tcp
52.22.227.22:443: connect: network is unreachable

## See Also

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/1.13/troubleshoot-reg)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.13/troubleshoot-requests)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=94de106a37279004b73669e8532d2f54445c6bffbf39389a1bc627601cc308f4 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-platform-connection.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Platform Connections

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring Flex Gateway, it is possible for the Flex Replica’s `registration.yaml` to be
absent or for the replica to lose its connection to Anypoint Platform.

To troubleshoot whether a registration file is present and whether Flex Gateway can make platform
connections, use the following command:

```ssh
flexctl check connections
```

The `flexctl check connections` command first ensures that a `registration.yaml` file is present.
Then it checks whether the replica can connect to the URLs defined in the registration file. If the
`flexctl check connections` command is successful, it returns the following `info` message:

$ flexctl check connections \[flexctl\]\[info\] Connection to platform endpoints successful.

## No Registration File Found

If the `registration.yaml` file isn’t found, Flex Gateway returns the following error message:

$ flexctl check connections Error: no registration config

To troubleshoot an absent registration file, check your Flex Replica configuration folder. To learn
more about registering a Flex Gateway, see following section for your relevant mode:

- [Registering and Running Flex Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-reg-run)

- [Registering and Running Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-reg-run)

## Failed Connection

There are multiple reasons why Flex Gateway might experience connection issues, such as an error in
the gateway’s environment or a network issue. How you troubleshoot your error depends on the error
returned.

If Flex Gateway can’t connect to a specific URL, it returns an error message that includes the
unreachable URL and the error message returned from the connection attempt. The following error
message is an example of an error returned due to no internet connection:

$ flexctl check connections Error: failed connecting to https://anypoint.mulesoft.com/: dial tcp
52.22.227.22:443: connect: network is unreachable

## See Also

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-reg)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-requests)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=75aafa47c0cdaa6f0184b6ecc34b46b64aef02daa336866edcbf2efe1adaa5ec url=/mulesoft/current/en-us/gateway/latest/troubleshoot-platform-connection.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Platform Connections

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring Omni Gateway, it is possible for the Omni Replica’s `registration.yaml` to be
absent or for the replica to lose its connection to Anypoint Platform.

To troubleshoot whether a registration file is present and whether Omni Gateway can make platform
connections, use the following command:

```ssh
flexctl check connections
```

The `flexctl check connections` command first ensures that a `registration.yaml` file is present.
Then it checks whether the replica can connect to the URLs defined in the registration file. If the
`flexctl check connections` command is successful, it returns the following `info` message:

$ flexctl check connections \[flexctl\]\[info\] Connection to platform endpoints successful.

## No Registration File Found

If the `registration.yaml` file isn’t found, Omni Gateway returns the following error message:

$ flexctl check connections Error: no registration config

To troubleshoot an absent registration file, check your Omni Replica configuration folder. To learn
more about registering an Omni Gateway, see following section for your relevant mode:

- [Registering and Running Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-reg-run)

- [Registering and Running Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-reg-run)

## Failed Connection

There are multiple reasons why Omni Gateway might experience connection issues, such as an error in
the gateway’s environment or a network issue. How you troubleshoot your error depends on the error
returned.

If Omni Gateway can’t connect to a specific URL, it returns an error message that includes the
unreachable URL and the error message returned from the connection attempt. The following error
message is an example of an error returned due to no internet connection:

$ flexctl check connections Error: failed connecting to https://anypoint.mulesoft.com/: dial tcp
52.22.227.22:443: connect: network is unreachable

## See Also

- [Troubleshooting Registration Issues](https://docs.mulesoft.com/gateway/latest/troubleshoot-reg)

- [Troubleshooting Request Connection](https://docs.mulesoft.com/gateway/latest/troubleshoot-requests)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=1edfcde2a6b62ffcccb3b608ec7e2fb6316a46b2acc54c689d33f9f188234709 url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-reg.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Registration Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When registering Anypoint Flex Gateway, you might encounter issues caused by incorrect access
permissions, and so on. The following topics provide possible causes for registration issues and
describe how to troubleshoot:

- [Performing Registration as a User Without Necessary Access Permissions](#no-permissions)

## Performing Registration as a User Without Necessary Access Permissions

Executing the registration command without having correct permissions can result in an error:

Couldn't execute register command successfully: rpc error: code = Internal desc = handler returned
neither error nor response message

### Cause

This issue occurs when the credentials that you provide for registration do not have the required
permissions.

### Solution

To resolve this error, perform the following steps:

1.  Navigate to **Access Management** as the organization administrator.

2.  Select **Users** from the main menu.

3.  Select the target organization user from the **Users** menu.

4.  From the **Permissions** tab, select **Runtime Manager**.

5.  Specify the environment in which to apply your permissions.

6.  Select the following from the **Select access** dropdown menu:

    - _Manage Servers_

    - _Read Servers_

7.  Click the **+** button.

Re-running the registration command should now result in success.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=0c9254be4fa6dfd52bd34e96a6582d6463efb1b06ade2ac5e2847ff7e88de34e url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-reg.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Registration Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When registering Omni Gateway, you might encounter issues caused by incorrect access permissions,
and so on. The following topics provide possible causes for registration issues and describe how to
troubleshoot:

- [Performing Registration as a User Without Necessary Access Permissions](#no-permissions)

## Performing Registration as a User Without Necessary Access Permissions

Executing the registration command without having correct permissions can result in an error:

Couldn't execute register command successfully: rpc error: code = Internal desc = handler returned
neither error nor response message

### Cause

This issue occurs when the credentials that you provide for registration do not have the required
permissions.

### Solution

To resolve this error, perform the following steps:

1.  Navigate to **Access Management** as the organization administrator.

2.  Select **Users** from the main menu.

3.  Select the target organization user from the **Users** menu.

4.  From the **Permissions** tab, select **Runtime Manager**.

5.  Specify the environment in which to apply your permissions.

6.  Select the following from the **Select access** dropdown menu:

    - _Manage Servers_

    - _Read Servers_

7.  Click the **+** button.

Re-running the registration command should now result in success.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=9d237f87e7e68ad93bb513729463a661275a5640cec2fbaf8be50a44d224e198 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-reg.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Registration Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When registering Anypoint Flex Gateway, you might encounter issues caused by incorrect access
permissions, and so on. The following topics provide possible causes for registration issues and
describe how to troubleshoot:

- [Performing Registration as a User Without Necessary Access Permissions](#no-permissions)

## Performing Registration as a User Without Necessary Access Permissions

Executing the registration command without having correct permissions can result in an error:

Couldn't execute register command successfully: rpc error: code = Internal desc = handler returned
neither error nor response message

### Cause

This issue occurs when the credentials that you provide for registration do not have the required
permissions.

### Solution

To resolve this error, perform the following steps:

1.  Navigate to **Access Management** as the organization administrator.

2.  Select **Users** from the main menu.

3.  Select the target organization user from the **Users** menu.

4.  From the **Permissions** tab, select **Runtime Manager**.

5.  Specify the environment in which to apply your permissions.

6.  Select the following from the **Select access** dropdown menu:

    - _Manage Servers_

    - _Read Servers_

7.  Click the **+** button.

Re-running the registration command should now result in success.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=cd5efc38ab7013e1689a857dd4c84ad994c2a62a442ba923a979772fd6adf1b4 url=/mulesoft/current/en-us/gateway/latest/troubleshoot-reg.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Registration Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When registering Omni Gateway, you might encounter issues caused by incorrect access permissions,
and so on. The following topics provide possible causes for registration issues and describe how to
troubleshoot:

- [Performing Registration as a User Without Necessary Access Permissions](#no-permissions)

## Performing Registration as a User Without Necessary Access Permissions

Executing the registration command without having correct permissions can result in an error:

Couldn't execute register command successfully: rpc error: code = Internal desc = handler returned
neither error nor response message

### Cause

This issue occurs when the credentials that you provide for registration do not have the required
permissions.

### Solution

To resolve this error, perform the following steps:

1.  Navigate to **Access Management** as the organization administrator.

2.  Select **Users** from the main menu.

3.  Select the target organization user from the **Users** menu.

4.  From the **Permissions** tab, select **Runtime Manager**.

5.  Specify the environment in which to apply your permissions.

6.  Select the following from the **Select access** dropdown menu:

    - _Manage Servers_

    - _Read Servers_

7.  Click the **+** button.

Re-running the registration command should now result in success.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=c88900cbe539d9cfd6eced2e2231d37226aa39e1a104fa00f5b6fb3c18f54328 url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-regex.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Regular Expression Compatibility Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot compatibility issues that occur when using regular expressions:

- [Negative Lookaheads](#troubleshoot-negative-lookaheads)

## Negative Lookaheads

Flex Gateway conforms to
[Google RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax), which does not
support negative lookaheads.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=cb1c83088cf8d2f5da1837f9c84382ed555af1375706815bcd36b723bee7c6bb url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-regex.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Regular Expression Compatibility Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot compatibility issues that occur when using regular expressions:

- [Negative Lookaheads](#troubleshoot-negative-lookaheads)

## Negative Lookaheads

Omni Gateway conforms to
[Google RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax), which does not
support negative lookaheads.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=92db2e8555c949e17fb95b4d484e24a471b648275b710bd9b7469bded9daa353 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-regex.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Regular Expression Compatibility Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot compatibility issues that occur when using regular expressions:

- [Negative Lookaheads](#troubleshoot-negative-lookaheads)

## Negative Lookaheads

Flex Gateway conforms to
[Google RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax), which does not
support negative lookaheads.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=cf55a287a95c6a698ac0dee76dcfb4c2bb33e5e9d035aefe3d09cdd22465b21a url=/mulesoft/current/en-us/gateway/latest/troubleshoot-regex.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Regular Expression Compatibility Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Troubleshoot compatibility issues that occur when using regular expressions:

- [Negative Lookaheads](#troubleshoot-negative-lookaheads)

## Negative Lookaheads

Omni Gateway conforms to
[Google RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax), which does not
support negative lookaheads.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=38ebaa379d7db0a9f0af9887e5a70bdc6ec0209544fe0fdf4931c3232b3bc866 url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-requests.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Request Connection

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring and running Flex Gateway, you might encounter connection issues.

To troubleshoot these issues, use the `flexctl check http` command. This command makes direct
requests to both the outbound connection between the upstream service and Flex Gateway and the
inbound connection between Flex Gateway and the client. Making direct requests isolates Flex Gateway
connections, which allows you to localize the issue.

The following diagram demonstrates the difference between inbound and outbound requests.

![Inbound connections are between the client and Flex Gateway and outbound connections are between Flex Gateway and the upstream service](/mulesoft/current/en-us/gateway/1.12/_images/flex-inbound-outbound-requests.png)

## Outbound Requests Between Flex Gateway and the Upstream Service

Isolating the connection between the upstream service and Flex Gateway enables you to test for
connection between the two.

To make a direct outbound request to the upstream service:

1.  Log into the Flex Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to the upstream service:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' <http://upstream.domain>
    ```

## Inbound Requests Between the Client and Flex Gateway

Isolating the connection between Flex Gateway and the client enables you to test if the connection
issue is due to a load balancer or another system added between Flex Gateway and the client.

To make a direct inbound request to the client:

1.  Log into the Flex Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to Flex Gateway:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' http://localhost:<api-instance-port>/<path>
    ```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=9b9cccaf62631ec1275066a602f61a189641a1f72f1dde4a837c3b6cac855a8a url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-requests.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Request Connection

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring and running Omni Gateway, you might encounter connection issues.

To troubleshoot these issues, use the `flexctl check http` command. This command makes direct
requests to both the outbound connection between the upstream service and Omni Gateway and the
inbound connection between Omni Gateway and the client. Making direct requests isolates Omni Gateway
connections, which allows you to localize the issue.

The following diagram demonstrates the difference between inbound and outbound requests.

![Inbound connections are between the client and Omni Gateway and outbound connections are between Omni Gateway and the upstream service](/mulesoft/current/en-us/gateway/1.13/_images/inbound-outbound-requests.png)

## Outbound Requests Between Omni Gateway and the Upstream Service

Isolating the connection between the upstream service and Omni Gateway enables you to test for
connection between the two.

To make a direct outbound request to the upstream service:

1.  Log into the Omni Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to the upstream service:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' <http://upstream.domain>
    ```

## Inbound Requests Between the Client and Omni Gateway

Isolating the connection between Omni Gateway and the client enables you to test if the connection
issue is due to a load balancer or another system added between Omni Gateway and the client.

To make a direct inbound request to the client:

1.  Log into the Omni Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to Omni Gateway:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' http://localhost:<api-instance-port>/<path>
    ```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=286a880e9cf7ec18ac293a962e56b0e58d3a549fc2ef9943c4b7cbea67cd0911 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-requests.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Request Connection

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring and running Flex Gateway, you might encounter connection issues.

To troubleshoot these issues, use the `flexctl check http` command. This command makes direct
requests to both the outbound connection between the upstream service and Flex Gateway and the
inbound connection between Flex Gateway and the client. Making direct requests isolates Flex Gateway
connections, which allows you to localize the issue.

The following diagram demonstrates the difference between inbound and outbound requests.

![Inbound connections are between the client and Flex Gateway and outbound connections are between Flex Gateway and the upstream service](/mulesoft/current/en-us/gateway/1.9/_images/flex-inbound-outbound-requests.png)

## Outbound Requests Between Flex Gateway and the Upstream Service

Isolating the connection between the upstream service and Flex Gateway enables you to test for
connection between the two.

To make a direct outbound request to the upstream service:

1.  Log into the Flex Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to the upstream service:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' <http://upstream.domain>
    ```

## Inbound Requests Between the Client and Flex Gateway

Isolating the connection between Flex Gateway and the client enables you to test if the connection
issue is due to a load balancer or another system added between Flex Gateway and the client.

To make a direct inbound request to the client:

1.  Log into the Flex Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to Flex Gateway:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' http://localhost:<api-instance-port>/<path>
    ```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=4fbe8c1cca6997b1548f7f178247788cc08fd83b796e87546c6f43bebe4b0c2f url=/mulesoft/current/en-us/gateway/latest/troubleshoot-requests.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Request Connection

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring and running Omni Gateway, you might encounter connection issues.

To troubleshoot these issues, use the `flexctl check http` command. This command makes direct
requests to both the outbound connection between the upstream service and Omni Gateway and the
inbound connection between Omni Gateway and the client. Making direct requests isolates Omni Gateway
connections, which allows you to localize the issue.

The following diagram demonstrates the difference between inbound and outbound requests.

![Inbound connections are between the client and Omni Gateway and outbound connections are between Omni Gateway and the upstream service](/mulesoft/current/en-us/gateway/latest/_images/inbound-outbound-requests.png)

## Outbound Requests Between Omni Gateway and the Upstream Service

Isolating the connection between the upstream service and Omni Gateway enables you to test for
connection between the two.

To make a direct outbound request to the upstream service:

1.  Log into the Omni Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to the upstream service:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' <http://upstream.domain>
    ```

## Inbound Requests Between the Client and Omni Gateway

Isolating the connection between Omni Gateway and the client enables you to test if the connection
issue is due to a load balancer or another system added between Omni Gateway and the client.

To make a direct inbound request to the client:

1.  Log into the Omni Gateway container or VM:

    - Linux:

      ```ssh
      ssh [-i sshkey.pem] <user>@<domain>
      ```

    - Docker:

      ```ssh
      docker exec -it <container-id> bash
      ```

    - Kubernetes:

      ```ssh
      kubectl -n <namespace> exec -it <pod-name> -- bash
      ```

2.  Make a request to Omni Gateway:

    ```ssh
    flexctl check http -X=POST -d='{\"key\": \"value\"}' -H='Authorization:token' http://localhost:<api-instance-port>/<path>
    ```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=30c41520dc8c7a9413732ae6fc5fd1a4df95badaa3eabef9f8c96e9c355d40cb url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-logging.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Self-Managed Gateway Logging Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring logging for Anypoint Flex Gateway, you might encounter logging issues caused by
incorrect directory permissions, and so on. The following topics provide possible causes for logging
issues and describe how to troubleshoot:

- [Logs Do Not Appear in a Third-Party Logging Service](#third-party-service)

- [Logs Do Not Appear when Running in a VM](#incorrect-permissions)

## Logs Do Not Appear in a Third-Party Logging Service

After applying a logging configuration YAML file, logs should begin appearing within a few minutes.
If your logs do not appear in your third party logging service:

1.  Ensure that your third-party service is running.

2.  If the service is running, check the runtime logs for potential configuration errors.

    You can view the runtime logs for both Flex Gateways running in Connected Mode and Local Mode by
    following the steps in [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.12/flex-local-view-logs). Additionally, for
    Flex Gateways running in Connected Mode, you can
    [view runtime logs in Runtime Manager](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-runtime-manager).

    Potential configuration errors appear similar to the following:

    \[flex-gateway-fluent\] \[2023/09/07 20:17:49\] \[error\] \[output:http:http.1\]
    hzk83039.live.dynatrace.com:443, HTTP status=401 \[flex-gateway-fluent\]
    {"error":{"code":401,"message":"Missing authorization parameter."}} \[flex-gateway-fluent\]
    \[2023/09/07 20:17:49\] \[ warn\] \[engine\] failed to flush chunk
    '20-1694117863.683606251.flb', retry in 7 seconds: task\_id=2,
    input=emitter\_for\_rewrite\_tag.11 > output=http.1 (out\_id=1)

3.  Whether or not configuration errors appear in the runtime logs, view the
    /var/tmp/mulesoft/flex-gateway/fluent-bit.conf file to ensure your configuration values are
    correct.

## Logs Do Not Appear when Running in a VM

Log files do not appear after specifying a target log directory in an access log policy. An example
log directory might be `/var/log`.

### Cause

Your log output directory might not have `write` permission.

### Solution

To resolve this issue, grant `write` permission to the output directory.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=d846b41806977905a94d82b45c49b653aeb760db3c0dc4ff5597b483034a2871 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-logging.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Self-Managed Gateway Logging Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring logging for Omni Gateway, you might encounter logging issues caused by incorrect
directory permissions, and so on. The following topics provide possible causes for logging issues
and describe how to troubleshoot:

- [Logs Do Not Appear in a Third-Party Logging Service](#third-party-service)

- [Logs Do Not Appear when Running in a VM](#incorrect-permissions)

## Logs Do Not Appear in a Third-Party Logging Service

After applying a logging configuration YAML file, logs should begin appearing within a few minutes.
If your logs do not appear in your third party logging service:

1.  Ensure that your third-party service is running.

2.  If the service is running, check the runtime logs for potential configuration errors.

    You can view the runtime logs for both Omni Gateways running in Connected Mode and Local Mode by
    following the steps in [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.13/local-view-logs). Additionally, for Omni
    Gateways running in Connected Mode, you can
    [view runtime logs in Runtime Manager](https://docs.mulesoft.com/gateway/1.13/view-logs-in-runtime-manager).

    Potential configuration errors appear similar to the following:

    \[flex-gateway-fluent\] \[2023/09/07 20:17:49\] \[error\] \[output:http:http.1\]
    hzk83039.live.dynatrace.com:443, HTTP status=401 \[flex-gateway-fluent\]
    {"error":{"code":401,"message":"Missing authorization parameter."}} \[flex-gateway-fluent\]
    \[2023/09/07 20:17:49\] \[ warn\] \[engine\] failed to flush chunk
    '20-1694117863.683606251.flb', retry in 7 seconds: task\_id=2,
    input=emitter\_for\_rewrite\_tag.11 > output=http.1 (out\_id=1)

3.  Whether or not configuration errors appear in the runtime logs, view the
    /var/tmp/mulesoft/flex-gateway/fluent-bit.conf file to ensure your configuration values are
    correct.

## Logs Do Not Appear when Running in a VM

Log files do not appear after specifying a target log directory in an access log policy. An example
log directory might be `/var/log`.

### Cause

Your log output directory might not have `write` permission.

### Solution

To resolve this issue, grant `write` permission to the output directory.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=d9eea0cbe660281fbffb70a6136b173ea72d5e0a5e37039f5a8a41bc3cf85405 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-logging.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Self-Managed Gateway Logging Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring logging for Anypoint Flex Gateway, you might encounter logging issues caused by
incorrect directory permissions, and so on. The following topics provide possible causes for logging
issues and describe how to troubleshoot:

- [Logs Do Not Appear in a Third-Party Logging Service](#third-party-service)

- [Logs Do Not Appear when Running in a VM](#incorrect-permissions)

## Logs Do Not Appear in a Third-Party Logging Service

After applying a logging configuration YAML file, logs should begin appearing within a few minutes.
If your logs do not appear in your third party logging service:

1.  Ensure that your third-party service is running.

2.  If the service is running, check the runtime logs for potential configuration errors.

    You can view the runtime logs for both Flex Gateways running in Connected Mode and Local Mode by
    following the steps in [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.9/flex-local-view-logs). Additionally, for
    Flex Gateways running in Connected Mode, you can
    [view runtime logs in Runtime Manager](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-runtime-manager).

    Potential configuration errors appear similar to the following:

    \[flex-gateway-fluent\] \[2023/09/07 20:17:49\] \[error\] \[output:http:http.1\]
    hzk83039.live.dynatrace.com:443, HTTP status=401 \[flex-gateway-fluent\]
    {"error":{"code":401,"message":"Missing authorization parameter."}} \[flex-gateway-fluent\]
    \[2023/09/07 20:17:49\] \[ warn\] \[engine\] failed to flush chunk
    '20-1694117863.683606251.flb', retry in 7 seconds: task\_id=2,
    input=emitter\_for\_rewrite\_tag.11 > output=http.1 (out\_id=1)

3.  Whether or not configuration errors appear in the runtime logs, view the
    /var/tmp/mulesoft/flex-gateway/fluent-bit.conf file to ensure your configuration values are
    correct.

## Logs Do Not Appear when Running in a VM

Log files do not appear after specifying a target log directory in an access log policy. An example
log directory might be `/var/log`.

### Cause

Your log output directory might not have `write` permission.

### Solution

To resolve this issue, grant `write` permission to the output directory.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=84749da304adae0bc84f442f6572ec16ae4de355be6d81f6c1ed37e76ee08462 url=/mulesoft/current/en-us/gateway/latest/troubleshoot-logging.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Self-Managed Gateway Logging Issues

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When configuring logging for Omni Gateway, you might encounter logging issues caused by incorrect
directory permissions, and so on. The following topics provide possible causes for logging issues
and describe how to troubleshoot:

- [Logs Do Not Appear in a Third-Party Logging Service](#third-party-service)

- [Logs Do Not Appear when Running in a VM](#incorrect-permissions)

## Logs Do Not Appear in a Third-Party Logging Service

After applying a logging configuration YAML file, logs should begin appearing within a few minutes.
If your logs do not appear in your third party logging service:

1.  Ensure that your third-party service is running.

2.  If the service is running, check the runtime logs for potential configuration errors.

    You can view the runtime logs for both Omni Gateways running in Connected Mode and Local Mode by
    following the steps in [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs). Additionally, for Omni
    Gateways running in Connected Mode, you can
    [view runtime logs in Runtime Manager](https://docs.mulesoft.com/gateway/latest/view-logs-in-runtime-manager).

    Potential configuration errors appear similar to the following:

    \[flex-gateway-fluent\] \[2023/09/07 20:17:49\] \[error\] \[output:http:http.1\]
    hzk83039.live.dynatrace.com:443, HTTP status=401 \[flex-gateway-fluent\]
    {"error":{"code":401,"message":"Missing authorization parameter."}} \[flex-gateway-fluent\]
    \[2023/09/07 20:17:49\] \[ warn\] \[engine\] failed to flush chunk
    '20-1694117863.683606251.flb', retry in 7 seconds: task\_id=2,
    input=emitter\_for\_rewrite\_tag.11 > output=http.1 (out\_id=1)

3.  Whether or not configuration errors appear in the runtime logs, view the
    /var/tmp/mulesoft/flex-gateway/fluent-bit.conf file to ensure your configuration values are
    correct.

## Logs Do Not Appear when Running in a VM

Log files do not appear after specifying a target log directory in an access log policy. An example
log directory might be `/var/log`.

### Cause

Your log output directory might not have `write` permission.

### Solution

To resolve this issue, grant `write` permission to the output directory.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=52fbdbd0a03db7de934e61ad1449946738550c7f63c2a7cf0e9997a14210328d url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-debug-logs.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting Self-Managed Gateway with Debug Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When troubleshooting Flex Gateway, set the runtime log level to `debug` for more verbose runtime
logs.

This page explains how to configure debug runtime logs. To configure debug access logs, set the
`level` parameter in your [Message Logging policy](https://docs.mulesoft.com/gateway/1.12/policies-included-message-logging) to `DEBUG`.

## Debug Logs Configuration Example

For both Connected Mode and Local Mode, configure debug runtime logs using the following YAML
configuration file:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    runtimeLogs:
      logLevel: debug
```

To configure debug runtime logs, use the previous YAML configuration file when prompted for your
configuration details in the following tutorials:

- [Configure External Logs in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-conn-third-party-logs-config)

- [Configure External Logs in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-third-party-logs-config)

If you have already configured a logging configuration file, set `logging.runtimeLogs.logLevel` to
`debug` in you current file to enable debug runtime logs. This does not affect the log output
location or access logs.

## See Also

To view runtime log output, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-runtime-manager)

- [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.12/flex-local-view-logs)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=1c4a856b9e43fe5c089b87332fa8952331caec40677202027ab323384db8de9f url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-debug-logs.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting Self-Managed Gateway with Debug Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When troubleshooting Omni Gateway, set the runtime log level to `debug` for more verbose runtime
logs.

This page explains how to configure debug runtime logs. To configure debug access logs, set the
`level` parameter in your [Message Logging policy](https://docs.mulesoft.com/gateway/1.13/policies-included-message-logging) to `DEBUG`.

## Debug Logs Configuration Example

For both Connected Mode and Local Mode, configure debug runtime logs using the following YAML
configuration file:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    runtimeLogs:
      logLevel: debug
```

To configure debug runtime logs, use the previous YAML configuration file when prompted for your
configuration details in the following tutorials:

- [Configure External Logs in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-third-party-logs-config)

- [Configure External Logs in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-third-party-logs-config)

If you have already configured a logging configuration file, set `logging.runtimeLogs.logLevel` to
`debug` in you current file to enable debug runtime logs. This does not affect the log output
location or access logs.

## See Also

To view runtime log output, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.13/view-logs-in-runtime-manager)

- [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.13/local-view-logs)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=9b19055404d952e18cfb79b7ead1c6ea817597039f73fbee5efb163ccc0b56ff url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-debug-logs.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting Self-Managed Gateway with Debug Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When troubleshooting Flex Gateway, set the runtime log level to `debug` for more verbose runtime
logs.

This page explains how to configure debug runtime logs. To configure debug access logs, set the
`level` parameter in your [Message Logging policy](https://docs.mulesoft.com/gateway/1.9/policies-included-message-logging) to `DEBUG`.

## Debug Logs Configuration Example

For both Connected Mode and Local Mode, configure debug runtime logs using the following YAML
configuration file:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    runtimeLogs:
      logLevel: debug
```

To configure debug runtime logs, use the previous YAML configuration file when prompted for your
configuration details in the following tutorials:

- [Configure External Logs in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-conn-third-party-logs-config)

- [Configure External Logs in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-third-party-logs-config)

If you have already configured a logging configuration file, set `logging.runtimeLogs.logLevel` to
`debug` in you current file to enable debug runtime logs. This does not affect the log output
location or access logs.

## See Also

To view runtime log output, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-runtime-manager)

- [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/1.9/flex-local-view-logs)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=7a8d8427488caabc6ad341e5f96e2c179e312947f33b8254e6187f620904a87e url=/mulesoft/current/en-us/gateway/latest/troubleshoot-debug-logs.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting Self-Managed Gateway with Debug Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When troubleshooting Omni Gateway, set the runtime log level to `debug` for more verbose runtime
logs.

This page explains how to configure debug runtime logs. To configure debug access logs, set the
`level` parameter in your [Message Logging policy](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging) to `DEBUG`.

## Debug Logs Configuration Example

For both Connected Mode and Local Mode, configure debug runtime logs using the following YAML
configuration file:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging-config
spec:
  logging:
    runtimeLogs:
      logLevel: debug
```

To configure debug runtime logs, use the previous YAML configuration file when prompted for your
configuration details in the following tutorials:

- [Configure External Logs in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-third-party-logs-config)

- [Configure External Logs in Local Mode](https://docs.mulesoft.com/gateway/latest/local-third-party-logs-config)

If you have already configured a logging configuration file, set `logging.runtimeLogs.logLevel` to
`debug` in you current file to enable debug runtime logs. This does not affect the log output
location or access logs.

## See Also

To view runtime log output, see:

- [Viewing Runtime Logs in Runtime Manager in Connected Mode](https://docs.mulesoft.com/gateway/latest/view-logs-in-runtime-manager)

- [Viewing Standard Output Logs](https://docs.mulesoft.com/gateway/latest/local-view-logs)

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=bcbdcae878008102150937298c3c9eadf34dd02db4dffc93421f6adfff1f7d2a url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-soap-apis.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting SOAP APIs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway does not natively support SOAP APIs and does not provide any schema validation for XML.
However, you can publish an HTTP API instance to a secure SOAP upstream service.

To create an HTTP API instance to a secure SOAP API upstream service, refer to the following:

- [Publishing Managed Gateway and Connected Mode APIs](https://docs.mulesoft.com/gateway/1.9/flex-gateway-publish-apis-conn)

- [Publishing Local Mode APIs](https://docs.mulesoft.com/gateway/1.9/flex-gateway-publish-apis-local)

## Publish a Soap API

Refer to the following video for additional information about how to publish a SOAP API as an HTTP
API instance:

![](https://play.vidyard.com/egZPDMSw2nMkfXxYPvbWUx.jpg)

## SOAP API Policy Limitations

Flex Gateway policies return JSON error messages when the policy blocks a request. Most SOAP clients
cannot read the JSON messages.

SOAP APIs do not support the following policies:

- [Schema Validation Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-schema-validation)

- [JSON Threat Protection Policy](https://docs.mulesoft.com/gateway/1.9/policies-included-json-threat-protection)

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=b6ab705eb48bfcf729d9830a8dbe0adf5021b59c96c1549d10665a86afb5d1d2 url=/mulesoft/current/en-us/gateway/1.12/flex-troubleshoot-admin-api.md -->

---
product: Omni Gateway
version: 1.12
---

# Troubleshooting with the CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway includes a `flexctl dump` CLI that enables you to query for information
related to a gateway’s API instances, services, configuration, and available extensions (policies).

As an example, the following inline configuration snippet defines a single API instance named
`jsonplaceholder-api` in the default namespace (it remains `default` because namespace is not
explicitly defined.) Additionally, the snippet defines one included policy:
`http-basic-authentication-flex`.

> [!NOTE] To run `flexctl dump` for Linux deployments, either add the user to the `flex` user group
> or run `flexctl dump` with the `sudo` command. To learn more, see
> [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/1.12/flex-troubleshoot-linux-permissions).

## Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: jsonplaceholder-api
spec: address: http://0.0.0.0:8080 services: jsonplaceholder: address:
https://jsonplaceholder.typicode.com:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) policies: - policyRef: name: http-basic-authentication-flex config: username:
chris password: admin

## Run the CLI

1.  To see JSON representations of your API instances, services, configurations, and extensions, run
    the following command:

    ```ssh
    flexctl dump
    ```

    > [!NOTE] When running in a Docker or Podman container, run the command in the container itself.

    The command outputs four files:

    - `api-instances.json`

    - `services.json`

    - `configuration.json`

    - `extensions.json`

2.  View any of the JSON file contents by running `cat` followed by the file name:

    - Api Instances

    - Services

    - Configuration

    - Extensions

    ```ssh
    cat api-instances.json
    ```

    The `api-instances.json` file contents resemble the following:

    \[ { "address":"http://0.0.0.0:8080", "kind":"ApiInstance", "name":"jsonplaceholder-api",
    "namespace":"default", "policies":\[ { "config":{ "password":"admin", "username":"chris" },
    "extension":{ "kind":"Extension", "name":"http-basic-authentication-flex", "namespace":"default"
    }, "kind":"Policy", "name":"jsonplaceholder-api-http-basic-authentication-flex-1",
    "namespace":"default" }, { "config":{ "destinationRef":{ "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } } "extension":{
    "kind":"Extension", "name":"route", "namespace":"default" }, "kind":"Policy",
    "name":"jsonplaceholder-api-jsonplaceholder-route-1", "namespace":"default", "order":50,
    "rules":\[ { "path":"/api(/users/.\*)" }, { "path":"/api(/comments/.\*)" } \] }, { "extension":{
    "kind":"Extension", "name":"envoy.filters.http.router", "namespace":"default" },
    "kind":"Policy", "name":"envoy.filters.http.router", "namespace":"default", "order":2147483647 }
    \] } \]

    ```ssh
    cat services.json
    ```

    The `services.json` file contents resemble the following:

    \[ { "address":"https://jsonplaceholder.typicode.com:443/", "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } \]

    ```ssh
    cat configuration.json
    ```

    The `configuration.json` file contents resemble the following:

    { "internalMetrics": { "enabled": false }, "logging": {}, "platformConnection": { "anypoint": {
    "url": "https://anypoint.mulesoft.com" }, "environment": { "cluster\_id":
    "4aa281e9-1a1d-4c56-8669-2d887b2e1938", "env\_id": "ad067f80-69ee-4abb-9d05-bec98ece1e20",
    "org\_id": "1caa0b9b-4f4d-43c4-a1b6-f925a8c77baa" }, "logging": { "certificate": { "cert":
    "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://logging.ingestion.us-east-1.msap.io/ingestion/api/v1/logging" }, "metering": {
    "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://metering.ingestion.us-east-1.msap.io/ingestion/api/v1/metering" }, "mode": "offline",
    "monitoring": { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://monitoring.ingestion.us-east-1.msap.io/ingestion/api/v1/monitoring" }, "runtimeEvents":
    { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://anypoint.mulesoft.com/apiruntime/v1/events" } }, "resourceLimits": { "apiInstances":
    100, "policies": 400 }, "sharedStorage": {}, "version": "1.1.0" }

    ```ssh
    cat extensions.json
    ```

    The `extensions.json` file contains all the policies available in Flex Gateway. The file
    contents resemble the following:

    { "extends": \[ { "kind": "Extension", "labels": { "flex.mulesoft.com/created-by":
    "flex-filesystem", "flex.mulesoft.com/managed-by": "flex-filesystem" }, "name":
    "extension-definition", "namespace": "default" }, { "kind": "Extension", "labels": {
    "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "extension-qos", "namespace": "default" } \], "kind": "Extension",
    "labels": { "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "header-injection-definition", "namespace": "default",
    "properties": \[ { "name": "config", "properties": \[ { "items": { "name": "inboundHeaders",
    "properties": \[ { "name": "key", "type": "stringOrDataweave" }, { "name": "value", "type":
    "stringOrDataweave" } \], "type": "object" }, "name": "inboundHeaders", "type": "array" }, {
    "items": { "name": "outboundHeaders", "properties": \[ { "name": "key", "type":
    "stringOrDataweave" }, { "name": "value", "type": "stringOrDataweave" } \], "type": "object" },
    "name": "outboundHeaders", "type": "array" } \], "type": "object" } \] }

## Change Verbosity Level

You can change the amount of information output by the `flexctl dump` CLI. For example, to increase
verbosity to a value of `10`, run `flexctl dump` with the following:

```ssh
flexctl dump -v 10
```

## Change Output Directory

Additionally, you can change the directory where `flexctl dump` outputs the four files. For example,
to output to `/tmp`, run `flexctl dump` with the following:

```ssh
flexctl dump --output-directory /tmp
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=a65d51329ffc8f66ebbc3a3f10b347e4bc3b46269201c45233da746d09a36815 url=/mulesoft/current/en-us/gateway/1.13/troubleshoot-admin-api.md -->

---
product: Omni Gateway
version: 1.13
---

# Troubleshooting with the CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway includes a `flexctl dump` CLI that enables you to query for information related to a
gateway’s API instances, services, configuration, and available extensions (policies).

As an example, the following inline configuration snippet defines a single API instance named
`jsonplaceholder-api` in the default namespace (it remains `default` because namespace is not
explicitly defined.) Additionally, the snippet defines one included policy:
`http-basic-authentication-flex`.

> [!NOTE] To run `flexctl dump` for Linux deployments, either add the user to the `flex` user group
> or run `flexctl dump` with the `sudo` command. To learn more, see
> [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/1.13/troubleshoot-linux-permissions).

## Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: jsonplaceholder-api
spec: address: http://0.0.0.0:8080 services: jsonplaceholder: address:
https://jsonplaceholder.typicode.com:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) policies: - policyRef: name: http-basic-authentication-flex config: username:
chris password: admin

## Run the CLI

1.  To see JSON representations of your API instances, services, configurations, and extensions, run
    the following command:

    ```ssh
    flexctl dump
    ```

    > [!NOTE] When running in a Docker or Podman container, run the command in the container itself.

    The command outputs four files:

    - `api-instances.json`

    - `services.json`

    - `configuration.json`

    - `extensions.json`

2.  View any of the JSON file contents by running `cat` followed by the file name:

    - Api Instances

    - Services

    - Configuration

    - Extensions

    ```ssh
    cat api-instances.json
    ```

    The `api-instances.json` file contents resemble the following:

    \[ { "address":"http://0.0.0.0:8080", "kind":"ApiInstance", "name":"jsonplaceholder-api",
    "namespace":"default", "policies":\[ { "config":{ "password":"admin", "username":"chris" },
    "extension":{ "kind":"Extension", "name":"http-basic-authentication-flex", "namespace":"default"
    }, "kind":"Policy", "name":"jsonplaceholder-api-http-basic-authentication-flex-1",
    "namespace":"default" }, { "config":{ "destinationRef":{ "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } } "extension":{
    "kind":"Extension", "name":"route", "namespace":"default" }, "kind":"Policy",
    "name":"jsonplaceholder-api-jsonplaceholder-route-1", "namespace":"default", "order":50,
    "rules":\[ { "path":"/api(/users/.\*)" }, { "path":"/api(/comments/.\*)" } \] }, { "extension":{
    "kind":"Extension", "name":"envoy.filters.http.router", "namespace":"default" },
    "kind":"Policy", "name":"envoy.filters.http.router", "namespace":"default", "order":2147483647 }
    \] } \]

    ```ssh
    cat services.json
    ```

    The `services.json` file contents resemble the following:

    \[ { "address":"https://jsonplaceholder.typicode.com:443/", "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } \]

    ```ssh
    cat configuration.json
    ```

    The `configuration.json` file contents resemble the following:

    { "internalMetrics": { "enabled": false }, "logging": {}, "platformConnection": { "anypoint": {
    "url": "https://anypoint.mulesoft.com" }, "environment": { "cluster\_id":
    "4aa281e9-1a1d-4c56-8669-2d887b2e1938", "env\_id": "ad067f80-69ee-4abb-9d05-bec98ece1e20",
    "org\_id": "1caa0b9b-4f4d-43c4-a1b6-f925a8c77baa" }, "logging": { "certificate": { "cert":
    "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://logging.ingestion.us-east-1.msap.io/ingestion/api/v1/logging" }, "metering": {
    "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://metering.ingestion.us-east-1.msap.io/ingestion/api/v1/metering" }, "mode": "offline",
    "monitoring": { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://monitoring.ingestion.us-east-1.msap.io/ingestion/api/v1/monitoring" }, "runtimeEvents":
    { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://anypoint.mulesoft.com/apiruntime/v1/events" } }, "resourceLimits": { "apiInstances":
    100, "policies": 400 }, "sharedStorage": {}, "version": "1.1.0" }

    ```ssh
    cat extensions.json
    ```

    The `extensions.json` file contains all the policies available in Omni Gateway. The file
    contents resemble the following:

    { "extends": \[ { "kind": "Extension", "labels": { "flex.mulesoft.com/created-by":
    "flex-filesystem", "flex.mulesoft.com/managed-by": "flex-filesystem" }, "name":
    "extension-definition", "namespace": "default" }, { "kind": "Extension", "labels": {
    "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "extension-qos", "namespace": "default" } \], "kind": "Extension",
    "labels": { "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "header-injection-definition", "namespace": "default",
    "properties": \[ { "name": "config", "properties": \[ { "items": { "name": "inboundHeaders",
    "properties": \[ { "name": "key", "type": "stringOrDataweave" }, { "name": "value", "type":
    "stringOrDataweave" } \], "type": "object" }, "name": "inboundHeaders", "type": "array" }, {
    "items": { "name": "outboundHeaders", "properties": \[ { "name": "key", "type":
    "stringOrDataweave" }, { "name": "value", "type": "stringOrDataweave" } \], "type": "object" },
    "name": "outboundHeaders", "type": "array" } \], "type": "object" } \] }

## Change Verbosity Level

You can change the amount of information output by the `flexctl dump` CLI. For example, to increase
verbosity to a value of `10`, run `flexctl dump` with the following:

```ssh
flexctl dump -v 10
```

## Change Output Directory

Additionally, you can change the directory where `flexctl dump` outputs the four files. For example,
to output to `/tmp`, run `flexctl dump` with the following:

```ssh
flexctl dump --output-directory /tmp
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=1e85fa15cb0018f06188059f2a41e7c70b87f9118b748bbacec3ca043fcd88b2 url=/mulesoft/current/en-us/gateway/1.9/flex-troubleshoot-admin-api.md -->

---
product: Omni Gateway
version: 1.9
---

# Troubleshooting with the CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Anypoint Flex Gateway includes a `flexctl dump` CLI that enables you to query for information
related to a gateway’s API instances, services, configuration, and available extensions (policies).

As an example, the following inline configuration snippet defines a single API instance named
`jsonplaceholder-api` in the default namespace (it remains `default` because namespace is not
explicitly defined.) Additionally, the snippet defines one included policy:
`http-basic-authentication-flex`.

> [!NOTE] To run `flexctl dump` for Linux deployments, either add the user to the `flex` user group
> or run `flexctl dump` with the `sudo` command. To learn more, see
> [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/1.9/flex-troubleshoot-linux-permissions).

## Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: jsonplaceholder-api
spec: address: http://0.0.0.0:8080 services: jsonplaceholder: address:
https://jsonplaceholder.typicode.com:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) policies: - policyRef: name: http-basic-authentication-flex config: username:
chris password: admin

## Run the CLI

1.  To see JSON representations of your API instances, services, configurations, and extensions, run
    the following command:

    ```ssh
    flexctl dump
    ```

    > [!NOTE] When running in a Docker or Podman container, run the command in the container itself.

    The command outputs four files:

    - `api-instances.json`

    - `services.json`

    - `configuration.json`

    - `extensions.json`

2.  View any of the JSON file contents by running `cat` followed by the file name:

    - Api Instances

    - Services

    - Configuration

    - Extensions

    ```ssh
    cat api-instances.json
    ```

    The `api-instances.json` file contents resemble the following:

    \[ { "address":"http://0.0.0.0:8080", "kind":"ApiInstance", "name":"jsonplaceholder-api",
    "namespace":"default", "policies":\[ { "config":{ "password":"admin", "username":"chris" },
    "extension":{ "kind":"Extension", "name":"http-basic-authentication-flex", "namespace":"default"
    }, "kind":"Policy", "name":"jsonplaceholder-api-http-basic-authentication-flex-1",
    "namespace":"default" }, { "config":{ "destinationRef":{ "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } } "extension":{
    "kind":"Extension", "name":"route", "namespace":"default" }, "kind":"Policy",
    "name":"jsonplaceholder-api-jsonplaceholder-route-1", "namespace":"default", "order":50,
    "rules":\[ { "path":"/api(/users/.\*)" }, { "path":"/api(/comments/.\*)" } \] }, { "extension":{
    "kind":"Extension", "name":"envoy.filters.http.router", "namespace":"default" },
    "kind":"Policy", "name":"envoy.filters.http.router", "namespace":"default", "order":2147483647 }
    \] } \]

    ```ssh
    cat services.json
    ```

    The `services.json` file contents resemble the following:

    \[ { "address":"https://jsonplaceholder.typicode.com:443/", "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } \]

    ```ssh
    cat configuration.json
    ```

    The `configuration.json` file contents resemble the following:

    { "internalMetrics": { "enabled": false }, "logging": {}, "platformConnection": { "anypoint": {
    "url": "https://anypoint.mulesoft.com" }, "environment": { "cluster\_id":
    "4aa281e9-1a1d-4c56-8669-2d887b2e1938", "env\_id": "ad067f80-69ee-4abb-9d05-bec98ece1e20",
    "org\_id": "1caa0b9b-4f4d-43c4-a1b6-f925a8c77baa" }, "logging": { "certificate": { "cert":
    "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://logging.ingestion.us-east-1.msap.io/ingestion/api/v1/logging" }, "metering": {
    "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://metering.ingestion.us-east-1.msap.io/ingestion/api/v1/metering" }, "mode": "offline",
    "monitoring": { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://monitoring.ingestion.us-east-1.msap.io/ingestion/api/v1/monitoring" }, "runtimeEvents":
    { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://anypoint.mulesoft.com/apiruntime/v1/events" } }, "resourceLimits": { "apiInstances":
    100, "policies": 400 }, "sharedStorage": {}, "version": "1.1.0" }

    ```ssh
    cat extensions.json
    ```

    The `extensions.json` file contains all the policies available in Flex Gateway. The file
    contents resemble the following:

    { "extends": \[ { "kind": "Extension", "labels": { "flex.mulesoft.com/created-by":
    "flex-filesystem", "flex.mulesoft.com/managed-by": "flex-filesystem" }, "name":
    "extension-definition", "namespace": "default" }, { "kind": "Extension", "labels": {
    "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "extension-qos", "namespace": "default" } \], "kind": "Extension",
    "labels": { "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "header-injection-definition", "namespace": "default",
    "properties": \[ { "name": "config", "properties": \[ { "items": { "name": "inboundHeaders",
    "properties": \[ { "name": "key", "type": "stringOrDataweave" }, { "name": "value", "type":
    "stringOrDataweave" } \], "type": "object" }, "name": "inboundHeaders", "type": "array" }, {
    "items": { "name": "outboundHeaders", "properties": \[ { "name": "key", "type":
    "stringOrDataweave" }, { "name": "value", "type": "stringOrDataweave" } \], "type": "object" },
    "name": "outboundHeaders", "type": "array" } \], "type": "object" } \] }

## Change Verbosity Level

You can change the amount of information output by the `flexctl dump` CLI. For example, to increase
verbosity to a value of `10`, run `flexctl dump` with the following:

```ssh
flexctl dump -v 10
```

## Change Output Directory

Additionally, you can change the directory where `flexctl dump` outputs the four files. For example,
to output to `/tmp`, run `flexctl dump` with the following:

```ssh
flexctl dump --output-directory /tmp
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=5a397ff32cb737ff6c42f13ccbccfab46e57ee3f77ec73fefffd283694e39eb7 url=/mulesoft/current/en-us/gateway/latest/troubleshoot-admin-api.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Troubleshooting with the CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway includes a `flexctl dump` CLI that collects a full snapshot of the gateway’s runtime
state and writes it to a single ZIP file. The snapshot includes information related to a gateway’s
API instances, services, configuration, and available extensions (policies), along with logs, Envoy
statistics, and other diagnostic data.

The dump is assembled by the gateway and streamed directly to the CLI. Each source is collected on a
best-effort basis: if a particular source is unavailable, that entry is omitted and the rest of the
ZIP is still produced.

As an example, the following inline configuration snippet defines a single API instance named
`jsonplaceholder-api` in the default namespace (it remains `default` because namespace is not
explicitly defined.) Additionally, the snippet defines one included policy:
`http-basic-authentication-flex`.

> [!NOTE] To run `flexctl dump` for Linux deployments, either add the user to the `flex` user group
> or run `flexctl dump` with the `sudo` command. To learn more, see
> [Troubleshooting Linux Permissions](https://docs.mulesoft.com/gateway/latest/troubleshoot-linux-permissions).

## Configuration Example

apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: jsonplaceholder-api
spec: address: http://0.0.0.0:8080 services: jsonplaceholder: address:
https://jsonplaceholder.typicode.com:443/ routes: - rules: - path: /api(/users/.\*) - path:
/api(/comments/.\*) policies: - policyRef: name: http-basic-authentication-flex config: username:
chris password: admin

## Run the CLI

1.  To collect a snapshot of the gateway’s runtime state, run the following command:

    ```ssh
    flexctl dump
    ```

    By default, the command writes the snapshot to a file named `dump.zip` in the current directory.

    > [!NOTE] When running in a Docker or Podman container, either run the command in the container
    > itself or stream the ZIP out of the container without entering it. To learn more, see
    > [Change the Output Location](#change-output-location).

2.  Extract the ZIP file to view its contents. The ZIP includes the following entries, among others:

    <table><colgroup><col> <col></colgroup><thead><tr><th>Entry</th><th>Description</th></tr></thead><tbody><tr><td><p><code>resources/ApiInstance.json</code></p></td><td><p>All API instances known to the gateway.</p></td></tr><tr><td><p><code>resources/Service.json</code></p></td><td><p>All services known to the gateway.</p></td></tr><tr><td><p><code>resources/Configuration.json</code></p></td><td><p>The gateway’s effective configuration.</p></td></tr><tr><td><p><code>resources/Extension.json</code></p></td><td><p>All extensions (policies) available in the gateway.</p></td></tr><tr><td><p><code>resources/PolicyBinding.json</code></p></td><td><p>All policy bindings.</p></td></tr><tr><td><p><code>logs/current</code></p></td><td><p>The current log file.</p></td></tr><tr><td><p><code>envoy/stats.json</code>, <code>envoy/config_dump.json</code>, <code>envoy/memory.json</code></p></td><td><p>Envoy statistics, configuration, and memory usage.</p></td></tr><tr><td><p><code>env/vars.json</code></p></td><td><p>The gateway process environment variables, with sensitive values redacted.</p></td></tr></tbody></table>

    > [!NOTE] Some entries appear only when the corresponding data is available in your deployment.

3.  View the contents of any extracted JSON file by running `cat` followed by the file name. For
    example, the extracted files resemble the following:

    - Api Instances

    - Services

    - Configuration

    - Extensions

    ```ssh
    cat resources/ApiInstance.json
    ```

    The `resources/ApiInstance.json` file contents resemble the following:

    \[ { "address":"http://0.0.0.0:8080", "kind":"ApiInstance", "name":"jsonplaceholder-api",
    "namespace":"default", "policies":\[ { "config":{ "password":"admin", "username":"chris" },
    "extension":{ "kind":"Extension", "name":"http-basic-authentication-flex", "namespace":"default"
    }, "kind":"Policy", "name":"jsonplaceholder-api-http-basic-authentication-flex-1",
    "namespace":"default" }, { "config":{ "destinationRef":{ "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } } "extension":{
    "kind":"Extension", "name":"route", "namespace":"default" }, "kind":"Policy",
    "name":"jsonplaceholder-api-jsonplaceholder-route-1", "namespace":"default", "order":50,
    "rules":\[ { "path":"/api(/users/.\*)" }, { "path":"/api(/comments/.\*)" } \] }, { "extension":{
    "kind":"Extension", "name":"envoy.filters.http.router", "namespace":"default" },
    "kind":"Policy", "name":"envoy.filters.http.router", "namespace":"default", "order":2147483647 }
    \] } \]

    ```ssh
    cat resources/Service.json
    ```

    The `resources/Service.json` file contents resemble the following:

    \[ { "address":"https://jsonplaceholder.typicode.com:443/", "kind":"Service",
    "name":"jsonplaceholder-api-jsonplaceholder", "namespace":"default" } \]

    ```ssh
    cat resources/Configuration.json
    ```

    The `resources/Configuration.json` file contents resemble the following:

    { "internalMetrics": { "enabled": false }, "logging": {}, "platformConnection": { "anypoint": {
    "url": "https://anypoint.mulesoft.com" }, "environment": { "cluster\_id":
    "4aa281e9-1a1d-4c56-8669-2d887b2e1938", "env\_id": "ad067f80-69ee-4abb-9d05-bec98ece1e20",
    "org\_id": "1caa0b9b-4f4d-43c4-a1b6-f925a8c77baa" }, "logging": { "certificate": { "cert":
    "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://logging.ingestion.us-east-1.msap.io/ingestion/api/v1/logging" }, "metering": {
    "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://metering.ingestion.us-east-1.msap.io/ingestion/api/v1/metering" }, "mode": "offline",
    "monitoring": { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://monitoring.ingestion.us-east-1.msap.io/ingestion/api/v1/monitoring" }, "runtimeEvents":
    { "certificate": { "cert": "demo-local.pem", "key": "demo-local.key" }, "url":
    "https://anypoint.mulesoft.com/apiruntime/v1/events" } }, "resourceLimits": { "apiInstances":
    100, "policies": 400 }, "sharedStorage": {}, "version": "1.1.0" }

    ```ssh
    cat resources/Extension.json
    ```

    The `resources/Extension.json` file contains all the policies available in Omni Gateway. The
    file contents resemble the following:

    { "extends": \[ { "kind": "Extension", "labels": { "flex.mulesoft.com/created-by":
    "flex-filesystem", "flex.mulesoft.com/managed-by": "flex-filesystem" }, "name":
    "extension-definition", "namespace": "default" }, { "kind": "Extension", "labels": {
    "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "extension-qos", "namespace": "default" } \], "kind": "Extension",
    "labels": { "flex.mulesoft.com/created-by": "flex-filesystem", "flex.mulesoft.com/managed-by":
    "flex-filesystem" }, "name": "header-injection-definition", "namespace": "default",
    "properties": \[ { "name": "config", "properties": \[ { "items": { "name": "inboundHeaders",
    "properties": \[ { "name": "key", "type": "stringOrDataweave" }, { "name": "value", "type":
    "stringOrDataweave" } \], "type": "object" }, "name": "inboundHeaders", "type": "array" }, {
    "items": { "name": "outboundHeaders", "properties": \[ { "name": "key", "type":
    "stringOrDataweave" }, { "name": "value", "type": "stringOrDataweave" } \], "type": "object" },
    "name": "outboundHeaders", "type": "array" } \], "type": "object" } \] }

## Change the Output Location

Use the `-o` (or `--output`) flag to write the ZIP file to a specific path, including the file name.
For example, to write the dump to `/tmp/my-dump.zip`, run the following command:

```ssh
flexctl dump -o /tmp/my-dump.zip
```

To stream the ZIP file to standard output instead of writing it to a file, pass either `-` or
`/dev/stdout` to the `-o` flag, and redirect the output:

```ssh
flexctl dump -o - > dump.zip
```

Streaming to standard output also lets you capture a dump from a container without entering it:

```ssh
docker exec flex-gateway flexctl dump -o - > dump.zip
```

## Change Verbosity Level

You can change the amount of information output by the `flexctl dump` CLI. For example, to increase
verbosity to a value of `10`, run `flexctl dump` with the following:

```ssh
flexctl dump -v 10
```

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=764a8e1a7402685cde9be055637373fbdb3ea39eec93044f8f7976d79063bf71 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-uninstall.md -->

---
product: Omni Gateway
version: 1.12
---

# Uninstall Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can uninstall Flex Gateway running as a Linux service, in a container, or in a Kubernetes
cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Uninstall Flex Gateway Running as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Uninstall Flex Gateway Running in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Uninstall Flex Gateway Running in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Uninstall Flex Gateway Running as a Linux Service

Flex Gateway can be uninstalled as any other package:

```ssh
sudo apt remove -y flex-gateway
```

## Uninstall Flex Gateway Running in a Docker Container

To uninstall Flex Gateway, stop and remove the Flex Gateway container:

1.  Determine the Flex Gateway container ID by listing all the running containers:

    ```ssh
    docker ps
    ```

2.  In the list of containers, note the container ID associated with the Flex Gateway container you
    want to uninstall.

3.  Stop the Flex Gateway container:

    ```ssh
    docker stop <container id>
    ```

    Replace `<container-id` with the container ID of the Flex Gateway container you want to stop:

4.  Remove the Flex Gateway container:

    ```ssh
    docker rm <container id>
    ```

    Replace `<container-id` with the container ID of the Flex Gateway container you want to remove.
    The command permanently deletes the container and its associated resources.

5.  Optionally, remove the Flex Gateway container image:

    ```ssh
    docker rmi mulesoft/flex-gateway
    ```

6.  To confirm that Flex Gateway is uninstalled, run the `docker ps` command again. The uninstalled
    container no longer appears in the list.

## Uninstall Flex Gateway Running in a Kubernetes Cluster

To uninstall Flex Gateway running in a Kubernetes cluster:

1.  Uninstall the Helm release. The following example removes a release called “my-release”:

    ```ssh
    helm delete my-release
    ```

    > [!NOTE] Update `my-release` to the release you have running. To see a list of all releases,
    > use the command `helm list -A`.

2.  Delete the release namespace if one was specified:

    ```ssh
    kubectl delete namespace gateway
    ```

3.  Delete the custom resource definitions:

    ```ssh
    kubectl delete crds \
         apiinstances.gateway.mulesoft.com \
         configurations.gateway.mulesoft.com \
         extensions.gateway.mulesoft.com \
         policybindings.gateway.mulesoft.com \
         services.gateway.mulesoft.com
    ```

<!-- document id=8ef6c8253386a50aa2934aa8dea484c442c840a6cdcd035ccf3789efdb5ed0b1 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-uninstall.md -->

---
product: Omni Gateway
version: 1.9
---

# Uninstall Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can uninstall Flex Gateway running as a Linux service, in a container, or in a Kubernetes
cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Uninstall Flex Gateway Running as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Uninstall Flex Gateway Running in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Uninstall Flex Gateway Running in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Uninstall Flex Gateway Running as a Linux Service

Flex Gateway can be uninstalled as any other package:

```ssh
sudo apt remove -y flex-gateway
```

## Uninstall Flex Gateway Running in a Docker Container

To uninstall Flex Gateway, stop and remove the Flex Gateway container:

1.  Determine the Flex Gateway container ID by listing all the running containers:

    ```ssh
    docker ps
    ```

2.  In the list of containers, note the container ID associated with the Flex Gateway container you
    want to uninstall.

3.  Stop the Flex Gateway container:

    ```ssh
    docker stop <container id>
    ```

    Replace `<container-id` with the container ID of the Flex Gateway container you want to stop:

4.  Remove the Flex Gateway container:

    ```ssh
    docker rm <container id>
    ```

    Replace `<container-id` with the container ID of the Flex Gateway container you want to remove.
    The command permanently deletes the container and its associated resources.

5.  Optionally, remove the Flex Gateway container image:

    ```ssh
    docker rmi mulesoft/flex-gateway
    ```

6.  To confirm that Flex Gateway is uninstalled, run the `docker ps` command again. The uninstalled
    container no longer appears in the list.

## Uninstall Flex Gateway Running in a Kubernetes Cluster

To uninstall Flex Gateway running in a Kubernetes cluster:

1.  Uninstall the Helm release. The following example removes a release called “my-release”:

    ```ssh
    helm delete my-release
    ```

    > [!NOTE] Update `my-release` to the release you have running. To see a list of all releases,
    > use the command `helm list -A`.

2.  Delete the release namespace if one was specified:

    ```ssh
    kubectl delete namespace gateway
    ```

3.  Delete the custom resource definitions:

    ```ssh
    kubectl delete crds \
         apiinstances.gateway.mulesoft.com \
         configurations.gateway.mulesoft.com \
         extensions.gateway.mulesoft.com \
         policybindings.gateway.mulesoft.com \
         services.gateway.mulesoft.com
    ```

<!-- document id=e28e9f2e3fc4a4640c0811c1cc34153aa5764c57d67efa5aecab769694655d60 url=/mulesoft/current/en-us/gateway/1.13/gateway-uninstall.md -->

---
product: Omni Gateway
version: 1.13
---

# Uninstall Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can uninstall Omni Gateway running as a Linux service, in a container, or in a Kubernetes
cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Uninstall Omni Gateway Running as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Uninstall Omni Gateway Running in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Uninstall Omni Gateway Running in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Uninstall Omni Gateway Running as a Linux Service

Omni Gateway can be uninstalled as any other package:

```ssh
sudo apt remove -y flex-gateway
```

## Uninstall Omni Gateway Running in a Docker Container

To uninstall Omni Gateway, stop and remove the Omni Gateway container:

1.  Determine the Omni Gateway container ID by listing all the running containers:

    ```ssh
    docker ps
    ```

2.  In the list of containers, note the container ID associated with the Omni Gateway container you
    want to uninstall.

3.  Stop the Omni Gateway container:

    ```ssh
    docker stop <container id>
    ```

    Replace `<container-id` with the container ID of the Omni Gateway container you want to stop:

4.  Remove the Omni Gateway container:

    ```ssh
    docker rm <container id>
    ```

    Replace `<container-id` with the container ID of the Omni Gateway container you want to remove.
    The command permanently deletes the container and its associated resources.

5.  Optionally, remove the Omni Gateway container image:

    ```ssh
    docker rmi mulesoft/flex-gateway
    ```

6.  To confirm that Omni Gateway is uninstalled, run the `docker ps` command again. The uninstalled
    container no longer appears in the list.

## Uninstall Omni Gateway Running in a Kubernetes Cluster

To uninstall Omni Gateway running in a Kubernetes cluster:

1.  Uninstall the Helm release. The following example removes a release called “my-release”:

    ```ssh
    helm delete my-release
    ```

    > [!NOTE] Update `my-release` to the release you have running. To see a list of all releases,
    > use the command `helm list -A`.

2.  Delete the release namespace if one was specified:

    ```ssh
    kubectl delete namespace gateway
    ```

3.  Delete the custom resource definitions:

    ```ssh
    kubectl delete crds \
         apiinstances.gateway.mulesoft.com \
         configurations.gateway.mulesoft.com \
         extensions.gateway.mulesoft.com \
         policybindings.gateway.mulesoft.com \
         services.gateway.mulesoft.com
    ```

<!-- document id=d61092ca98c729b5b7346a5c9b4a30e12a08752067ce9c0190d6667573f08941 url=/mulesoft/current/en-us/gateway/latest/gateway-uninstall.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Uninstall Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can uninstall Omni Gateway running as a Linux service, in a container, or in a Kubernetes
cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Uninstall Omni Gateway Running as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Uninstall Omni Gateway Running in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Uninstall Omni Gateway Running in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Uninstall Omni Gateway Running as a Linux Service

Omni Gateway can be uninstalled as any other package:

```ssh
sudo apt remove -y flex-gateway
```

## Uninstall Omni Gateway Running in a Docker Container

To uninstall Omni Gateway, stop and remove the Omni Gateway container:

1.  Determine the Omni Gateway container ID by listing all the running containers:

    ```ssh
    docker ps
    ```

2.  In the list of containers, note the container ID associated with the Omni Gateway container you
    want to uninstall.

3.  Stop the Omni Gateway container:

    ```ssh
    docker stop <container id>
    ```

    Replace `<container-id` with the container ID of the Omni Gateway container you want to stop:

4.  Remove the Omni Gateway container:

    ```ssh
    docker rm <container id>
    ```

    Replace `<container-id` with the container ID of the Omni Gateway container you want to remove.
    The command permanently deletes the container and its associated resources.

5.  Optionally, remove the Omni Gateway container image:

    ```ssh
    docker rmi mulesoft/flex-gateway
    ```

6.  To confirm that Omni Gateway is uninstalled, run the `docker ps` command again. The uninstalled
    container no longer appears in the list.

## Uninstall Omni Gateway Running in a Kubernetes Cluster

To uninstall Omni Gateway running in a Kubernetes cluster:

1.  Uninstall the Helm release. The following example removes a release called “my-release”:

    ```ssh
    helm delete my-release
    ```

    > [!NOTE] Update `my-release` to the release you have running. To see a list of all releases,
    > use the command `helm list -A`.

2.  Delete the release namespace if one was specified:

    ```ssh
    kubectl delete namespace gateway
    ```

3.  Delete the custom resource definitions:

    ```ssh
    kubectl delete crds \
         apiinstances.gateway.mulesoft.com \
         configurations.gateway.mulesoft.com \
         extensions.gateway.mulesoft.com \
         policybindings.gateway.mulesoft.com \
         services.gateway.mulesoft.com
    ```

<!-- document id=962730248cb1184994d6ac4001a36e923a1365bc4b74f1c1a06e09a49686c14a url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-k8-change-helm-settings.md -->

---
product: Omni Gateway
version: 1.12
---

# Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Change requirements for a Pod that contains a Flex Gateway deployment. The example in this guide
sets the following CPU and memory requirements in the Helm chart for a Flex Gateway deployment:

- `resources.limits.cpu=1500m`

- `resources.limits.memory=2048Mi`

- `resources.requests.cpu=260m`

- `resources.requests.memory=384Mi`

Use this example as a guide to updating values in the Helm chart for your Flex Gateway deployment.

Find the default Helm chart settings for Flex Gateway through one of the following methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window, for example,
  `helm show values flex-gateway/flex-gateway`.

For details about CPU and memory resource settings, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).

## Before You Begin

Register and deploy Flex Gateway to a Kubernetes cluster. For guidance, see
[Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-set-up) or
[Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.12/flex-gateway-k8-getting-started).

## Check the Current Settings of Your Helm Chart

Before updating settings for a Pod that contains a Flex Gateway deployment, check the Pod’s settings
for the current deployment.

1.  Ensure that your Helm repository is up and available by running the following command from a
    terminal window:

    ```helm
    helm repo up
    ```

2.  Find the `REVISION` number of the latest deployment.

    The following example requests the history of the `ingress` release in the `gateway` namespace:

    ```helm
    helm history ingress -n gateway
    ```

    The command returns a result similar to this one:

    REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION 1 Mon Mar 27 09:36:20 2023 superseded
    flex-gateway-1.4.2 1.4.2 Upgrade complete 2 Mon Mar 27 11:40:56 2023 deployed flex-gateway-1.4.2
    1.4.2 Upgrade complete

3.  Check for `USER-SUPPLIED VALUES` settings for `resources` in the currently deployed revision:

    Command Syntax:

    helm get values --revision=<version-number> <release-name> -n <namespace>

    Example:

    ```helm
    helm get values --revision=2 ingress -n gateway
    ```

    The following example shows the `resources` settings for the Pod’s CPU and memory below the
    Pod’s `registration` data:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1000m memory: 2024Mi requests:
    cpu: 250m memory: 256Mi

    This example displays settings from `REVISION` number `2`. The output displays only revised
    settings. If your chart has never revised the default Helm chart values, _no_ revisions appear
    in the output.

4.  Use one of the following procedures to change settings in the Helm chart for your Flex Gateway
    deployment:

    - [Modify Settings for Your Helm Chart](#use-helm-set-option) uses `--set` options in a
      `helm upgrade` command. The command allows multiple `--set` options.

    - [Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option) passes a
      configuration file with multiple settings though the `-f` option to `helm upgrade`. The
      command allows multiple `-f` options.

## Modify Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `--set` option
to pass new values individually to the Helm chart for your Flex Gateway deployment. Alternatively,
follow the procedure in
[Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option).

1.  Change the `cpu` and `memory` values by using the `helm upgrade` command.

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ --set <key-to-update>=<new-value> --set
    <next-key-to-update>=<new-value> ...

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    --set resources.limits.cpu=1500m \
    --set resources.limits.memory=2048Mi \
    --set resources.requests.cpu=260m \
    --set resources.requests.memory=384Mi
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    11:58:36 2023 NAMESPACE: gateway STATUS: deployed REVISION: 3 TEST SUITE: None

2.  Using the new `REVISION` value, check the `resources` settings, for example:

    ```helm
    helm get values --revision=3 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

## Provide a File with Modified Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `-f` option
with `helm upgrade` to identify the file that contains new Helm chart settings for your Flex Gateway
deployment. Alternatively, follow the procedure in
[Modify Settings for Your Helm Chart](#use-helm-set-option).

1.  Create a configuration file that contains your new settings.

    For example, create a YAML file named `my-config-file.yaml` that contains the new `cpu` and
    `memory` values:

    ```yaml
    resources:
      limits:
        cpu: 1500m
        memory: 2048Mi
      requests:
        cpu: 260m
        memory: 384Mi
    ```

2.  Pass the new values from your configuration file to your Helm chart, for example:

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ -f <your-settings-config-file>

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    -f my-config-file.yaml
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    16:38:07 2023 NAMESPACE: gateway STATUS: deployed REVISION: 4 TEST SUITE: None

3.  Using your Helm repository and chart names, verify the update to your chart, for example:

    ```helm
    helm get values --revision=4 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

<!-- document id=e0c6a131c5e203dcfe0f8908e7dff3a5b8dc48d588b57e3155b532b07175555d url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-k8-change-helm-settings.md -->

---
product: Omni Gateway
version: 1.9
---

# Update Pod Settings for a Flex Gateway Deployment Through a Helm Chart

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Change requirements for a Pod that contains a Flex Gateway deployment. The example in this guide
sets the following CPU and memory requirements in the Helm chart for a Flex Gateway deployment:

- `resources.limits.cpu=1500m`

- `resources.limits.memory=2048Mi`

- `resources.requests.cpu=260m`

- `resources.requests.memory=384Mi`

Use this example as a guide to updating values in the Helm chart for your Flex Gateway deployment.

Find the default Helm chart settings for Flex Gateway through one of the following methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window, for example,
  `helm show values flex-gateway/flex-gateway`.

For details about CPU and memory resource settings, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).

## Before You Begin

Register and deploy Flex Gateway to a Kubernetes cluster. For guidance, see
[Setting Up Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-set-up) or
[Getting Started with Self-Managed Flex Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.9/flex-gateway-k8-getting-started).

## Check the Current Settings of Your Helm Chart

Before updating settings for a Pod that contains a Flex Gateway deployment, check the Pod’s settings
for the current deployment.

1.  Ensure that your Helm repository is up and available by running the following command from a
    terminal window:

    ```helm
    helm repo up
    ```

2.  Find the `REVISION` number of the latest deployment.

    The following example requests the history of the `ingress` release in the `gateway` namespace:

    ```helm
    helm history ingress -n gateway
    ```

    The command returns a result similar to this one:

    REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION 1 Mon Mar 27 09:36:20 2023 superseded
    flex-gateway-1.4.2 1.4.2 Upgrade complete 2 Mon Mar 27 11:40:56 2023 deployed flex-gateway-1.4.2
    1.4.2 Upgrade complete

3.  Check for `USER-SUPPLIED VALUES` settings for `resources` in the currently deployed revision:

    Command Syntax:

    helm get values --revision=<version-number> <release-name> -n <namespace>

    Example:

    ```helm
    helm get values --revision=2 ingress -n gateway
    ```

    The following example shows the `resources` settings for the Pod’s CPU and memory below the
    Pod’s `registration` data:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1000m memory: 2024Mi requests:
    cpu: 250m memory: 256Mi

    This example displays settings from `REVISION` number `2`. The output displays only revised
    settings. If your chart has never revised the default Helm chart values, _no_ revisions appear
    in the output.

4.  Use one of the following procedures to change settings in the Helm chart for your Flex Gateway
    deployment:

    - [Modify Settings for Your Helm Chart](#use-helm-set-option) uses `--set` options in a
      `helm upgrade` command. The command allows multiple `--set` options.

    - [Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option) passes a
      configuration file with multiple settings though the `-f` option to `helm upgrade`. The
      command allows multiple `-f` options.

## Modify Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `--set` option
to pass new values individually to the Helm chart for your Flex Gateway deployment. Alternatively,
follow the procedure in
[Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option).

1.  Change the `cpu` and `memory` values by using the `helm upgrade` command.

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ --set <key-to-update>=<new-value> --set
    <next-key-to-update>=<new-value> ...

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    --set resources.limits.cpu=1500m \
    --set resources.limits.memory=2048Mi \
    --set resources.requests.cpu=260m \
    --set resources.requests.memory=384Mi
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    11:58:36 2023 NAMESPACE: gateway STATUS: deployed REVISION: 3 TEST SUITE: None

2.  Using the new `REVISION` value, check the `resources` settings, for example:

    ```helm
    helm get values --revision=3 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

## Provide a File with Modified Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `-f` option
with `helm upgrade` to identify the file that contains new Helm chart settings for your Flex Gateway
deployment. Alternatively, follow the procedure in
[Modify Settings for Your Helm Chart](#use-helm-set-option).

1.  Create a configuration file that contains your new settings.

    For example, create a YAML file named `my-config-file.yaml` that contains the new `cpu` and
    `memory` values:

    ```yaml
    resources:
      limits:
        cpu: 1500m
        memory: 2048Mi
      requests:
        cpu: 260m
        memory: 384Mi
    ```

2.  Pass the new values from your configuration file to your Helm chart, for example:

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ -f <your-settings-config-file>

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    -f my-config-file.yaml
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    16:38:07 2023 NAMESPACE: gateway STATUS: deployed REVISION: 4 TEST SUITE: None

3.  Using your Helm repository and chart names, verify the update to your chart, for example:

    ```helm
    helm get values --revision=4 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

<!-- document id=78d474c4fc4117af99f1a5acb0fefcd8230d5eeee4813d786bcde522339ecfd1 url=/mulesoft/current/en-us/gateway/1.13/gateway-k8-change-helm-settings.md -->

---
product: Omni Gateway
version: 1.13
---

# Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Change requirements for a Pod that contains an Omni Gateway deployment. The example in this guide
sets the following CPU and memory requirements in the Helm chart for an Omni Gateway deployment:

- `resources.limits.cpu=1500m`

- `resources.limits.memory=2048Mi`

- `resources.requests.cpu=260m`

- `resources.requests.memory=384Mi`

Use this example as a guide to updating values in the Helm chart for your Omni Gateway deployment.

Find the default Helm chart settings for Omni Gateway through one of the following methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window, for example,
  `helm show values flex-gateway/flex-gateway`.

For details about CPU and memory resource settings, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).

## Before You Begin

Register and deploy Omni Gateway to a Kubernetes cluster. For guidance, see
[Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-set-up) or
[Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/1.13/gateway-k8-getting-started).

## Check the Current Settings of Your Helm Chart

Before updating settings for a Pod that contains an Omni Gateway deployment, check the Pod’s
settings for the current deployment.

1.  Ensure that your Helm repository is up and available by running the following command from a
    terminal window:

    ```helm
    helm repo up
    ```

2.  Find the `REVISION` number of the latest deployment.

    The following example requests the history of the `ingress` release in the `gateway` namespace:

    ```helm
    helm history ingress -n gateway
    ```

    The command returns a result similar to this one:

    REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION 1 Mon Mar 27 09:36:20 2023 superseded
    flex-gateway-1.4.2 1.4.2 Upgrade complete 2 Mon Mar 27 11:40:56 2023 deployed flex-gateway-1.4.2
    1.4.2 Upgrade complete

3.  Check for `USER-SUPPLIED VALUES` settings for `resources` in the currently deployed revision:

    Command Syntax:

    helm get values --revision=<version-number> <release-name> -n <namespace>

    Example:

    ```helm
    helm get values --revision=2 ingress -n gateway
    ```

    The following example shows the `resources` settings for the Pod’s CPU and memory below the
    Pod’s `registration` data:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1000m memory: 2024Mi requests:
    cpu: 250m memory: 256Mi

    This example displays settings from `REVISION` number `2`. The output displays only revised
    settings. If your chart has never revised the default Helm chart values, _no_ revisions appear
    in the output.

4.  Use one of the following procedures to change settings in the Helm chart for your Omni Gateway
    deployment:

    - [Modify Settings for Your Helm Chart](#use-helm-set-option) uses `--set` options in a
      `helm upgrade` command. The command allows multiple `--set` options.

    - [Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option) passes a
      configuration file with multiple settings though the `-f` option to `helm upgrade`. The
      command allows multiple `-f` options.

## Modify Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `--set` option
to pass new values individually to the Helm chart for your Omni Gateway deployment. Alternatively,
follow the procedure in
[Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option).

1.  Change the `cpu` and `memory` values by using the `helm upgrade` command.

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ --set <key-to-update>=<new-value> --set
    <next-key-to-update>=<new-value> ...

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    --set resources.limits.cpu=1500m \
    --set resources.limits.memory=2048Mi \
    --set resources.requests.cpu=260m \
    --set resources.requests.memory=384Mi
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    11:58:36 2023 NAMESPACE: gateway STATUS: deployed REVISION: 3 TEST SUITE: None

2.  Using the new `REVISION` value, check the `resources` settings, for example:

    ```helm
    helm get values --revision=3 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

## Provide a File with Modified Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `-f` option
with `helm upgrade` to identify the file that contains new Helm chart settings for your Omni Gateway
deployment. Alternatively, follow the procedure in
[Modify Settings for Your Helm Chart](#use-helm-set-option).

1.  Create a configuration file that contains your new settings.

    For example, create a YAML file named `my-config-file.yaml` that contains the new `cpu` and
    `memory` values:

    ```yaml
    resources:
      limits:
        cpu: 1500m
        memory: 2048Mi
      requests:
        cpu: 260m
        memory: 384Mi
    ```

2.  Pass the new values from your configuration file to your Helm chart, for example:

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ -f <your-settings-config-file>

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    -f my-config-file.yaml
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    16:38:07 2023 NAMESPACE: gateway STATUS: deployed REVISION: 4 TEST SUITE: None

3.  Using your Helm repository and chart names, verify the update to your chart, for example:

    ```helm
    helm get values --revision=4 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

<!-- document id=3c07b122a54cdeb331f237536fbea56badf24bf66da43563a86ef8c83233fb5e url=/mulesoft/current/en-us/gateway/latest/gateway-k8-change-helm-settings.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Update Pod Settings for an Omni Gateway Deployment Through a Helm Chart

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Change requirements for a Pod that contains an Omni Gateway deployment. The example in this guide
sets the following CPU and memory requirements in the Helm chart for an Omni Gateway deployment:

- `resources.limits.cpu=1500m`

- `resources.limits.memory=2048Mi`

- `resources.requests.cpu=260m`

- `resources.requests.memory=384Mi`

Use this example as a guide to updating values in the Helm chart for your Omni Gateway deployment.

Find the default Helm chart settings for Omni Gateway through one of the following methods:

- Open the **flex-gateway** page in
  [ArtifactHUB](https://artifacthub.io/packages/helm/flex-gateway/flex-gateway)

- Run `helm show values <repository-name>/<chart-name>` from a terminal window, for example,
  `helm show values flex-gateway/flex-gateway`.

For details about CPU and memory resource settings, see the
[Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).

## Before You Begin

Register and deploy Omni Gateway to a Kubernetes cluster. For guidance, see
[Setting Up Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-set-up) or
[Getting Started with Self-Managed Omni Gateway in a Kubernetes Cluster](https://docs.mulesoft.com/gateway/latest/gateway-k8-getting-started).

## Check the Current Settings of Your Helm Chart

Before updating settings for a Pod that contains an Omni Gateway deployment, check the Pod’s
settings for the current deployment.

1.  Ensure that your Helm repository is up and available by running the following command from a
    terminal window:

    ```helm
    helm repo up
    ```

2.  Find the `REVISION` number of the latest deployment.

    The following example requests the history of the `ingress` release in the `gateway` namespace:

    ```helm
    helm history ingress -n gateway
    ```

    The command returns a result similar to this one:

    REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION 1 Mon Mar 27 09:36:20 2023 superseded
    flex-gateway-1.4.2 1.4.2 Upgrade complete 2 Mon Mar 27 11:40:56 2023 deployed flex-gateway-1.4.2
    1.4.2 Upgrade complete

3.  Check for `USER-SUPPLIED VALUES` settings for `resources` in the currently deployed revision:

    Command Syntax:

    helm get values --revision=<version-number> <release-name> -n <namespace>

    Example:

    ```helm
    helm get values --revision=2 ingress -n gateway
    ```

    The following example shows the `resources` settings for the Pod’s CPU and memory below the
    Pod’s `registration` data:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1000m memory: 2024Mi requests:
    cpu: 250m memory: 256Mi

    This example displays settings from `REVISION` number `2`. The output displays only revised
    settings. If your chart has never revised the default Helm chart values, _no_ revisions appear
    in the output.

4.  Use one of the following procedures to change settings in the Helm chart for your Omni Gateway
    deployment:

    - [Modify Settings for Your Helm Chart](#use-helm-set-option) uses `--set` options in a
      `helm upgrade` command. The command allows multiple `--set` options.

    - [Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option) passes a
      configuration file with multiple settings though the `-f` option to `helm upgrade`. The
      command allows multiple `-f` options.

## Modify Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `--set` option
to pass new values individually to the Helm chart for your Omni Gateway deployment. Alternatively,
follow the procedure in
[Provide a File with Modified Settings for Your Helm Chart](#use-helm-f-option).

1.  Change the `cpu` and `memory` values by using the `helm upgrade` command.

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ --set <key-to-update>=<new-value> --set
    <next-key-to-update>=<new-value> ...

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    --set resources.limits.cpu=1500m \
    --set resources.limits.memory=2048Mi \
    --set resources.requests.cpu=260m \
    --set resources.requests.memory=384Mi
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    11:58:36 2023 NAMESPACE: gateway STATUS: deployed REVISION: 3 TEST SUITE: None

2.  Using the new `REVISION` value, check the `resources` settings, for example:

    ```helm
    helm get values --revision=3 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

## Provide a File with Modified Settings for Your Helm Chart

After following the steps in
[Check the Current Settings of Your Helm Chart](#update-cpu-memory-example), use the `-f` option
with `helm upgrade` to identify the file that contains new Helm chart settings for your Omni Gateway
deployment. Alternatively, follow the procedure in
[Modify Settings for Your Helm Chart](#use-helm-set-option).

1.  Create a configuration file that contains your new settings.

    For example, create a YAML file named `my-config-file.yaml` that contains the new `cpu` and
    `memory` values:

    ```yaml
    resources:
      limits:
        cpu: 1500m
        memory: 2048Mi
      requests:
        cpu: 260m
        memory: 384Mi
    ```

2.  Pass the new values from your configuration file to your Helm chart, for example:

    Syntax:

    helm -n <namespace> upgrade <release-name> \\ --wait \\ --reuse-values \\
    <repository-name>/<chart-name> \\ -f <your-settings-config-file>

    Example:

    ```helm
    helm -n gateway upgrade ingress \
    --wait \
    --reuse-values \
    flex-gateway/flex-gateway \
    -f my-config-file.yaml
    ```

    When successful, the command returns output similar to this:

    Release "ingress" has been upgraded. Happy Helming! NAME: ingress LAST DEPLOYED: Mon Mar 27
    16:38:07 2023 NAMESPACE: gateway STATUS: deployed REVISION: 4 TEST SUITE: None

3.  Using your Helm repository and chart names, verify the update to your chart, for example:

    ```helm
    helm get values --revision=4 ingress -n gateway
    ```

    The output displays the new `resources` settings for the Pod:

    USER-SUPPLIED VALUES: registration: ... resources: limits: cpu: 1500m memory: 2048Mi requests:
    cpu: 260m memory: 384Mi

<!-- document id=f7c5d655221e78180451f04cd9ac13621deca744d6d9e49617b843afc44e8a95 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-managed-upgrade-delete.md -->

---
product: Omni Gateway
version: 1.12
---

# Upgrade or Delete Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade or delete a Managed Flex Gateway using Anypoint Runtime Manager.

Managed Flex Gateways are regularly auto-upgraded, depending on your Gateway release channel (LTS or
Edge). See [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.12/flex-gateway-version-lifecycle) for more information.

You can upgrade a Managed Flex Gateway earlier than the regularly scheduled upgrade or patching
process, between the new release date and the auto-upgrade date. You can choose the time that better
suits the needs of your organization.

## Early Upgrade Managed Flex Gateway (Optional)

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the **Managed Flex Gateway** tab.

4.  Click the name of the gateway to upgrade.

5.  Click **Settings** in the navigation menu.

6.  If a newer version is available, the **Version** field shows an **Update available** tag.

7.  Click the padlock symbol next to the version and **Update available** tag.

8.  Click the **Apply Changes** button.  
    A status message (**Your gateway is being updated**) appears while the upgrade is being applied.
    A success message (**Your gateway has been successfully updated**) appears when the upgrade is
    complete.

9.  Click **Dashboard** in the navigation menu to view your gateway status.

## Delete Managed Flex Gateway

You can delete a Managed Flex Gateway using Anypoint Runtime Manager.

### Before You Begin

If there are any APIs associated with the gateway you want to delete, you must either move the APIs
to another gateway or delete the APIs. After any associated APIs are moved or deleted, follow these
steps to delete a gateway and confirm the deletion.

### Delete Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the **Managed Flex Gateway** tab.

4.  Click the name of the gateway to delete.

5.  Ensure the action menu button says **Delete Gateway**. If it says **Stop Gateway**, click the
    down arrow part of this button, and select **Delete Gateway** to change the action.

6.  Click the action menu button **Delete Gateway**.

7.  Verify that you delete the correct gateway in the confirmation dialog.

8.  Click **Yes, Delete**.  
    A status message (**Your gateway is being deleted**) appears while the action is applied. A
    success message (**Your gateway has been successfully deleted**) appears when the action is
    complete.

> [!NOTE] If you delete a gateway, you lose its configuration history.

<!-- document id=1c37cbb40be497a6a5b2d9b8938b6501469874e3daf856ed80f2783f44ab9069 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-managed-upgrade-delete.md -->

---
product: Omni Gateway
version: 1.9
---

# Upgrade or Delete Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade or delete a Managed Flex Gateway using Anypoint Runtime Manager.

Managed Flex Gateways are regularly auto-upgraded, depending on your Gateway release channel (LTS or
Edge). See [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.9/flex-gateway-version-lifecycle) for more information.

You can upgrade a Managed Flex Gateway earlier than the regularly scheduled upgrade or patching
process, between the new release date and the auto-upgrade date. You can choose the time that better
suits the needs of your organization.

## Early Upgrade Managed Flex Gateway (Optional)

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the **Managed Flex Gateway** tab.

4.  Click the name of the gateway to upgrade.

5.  Click **Settings** in the navigation menu.

6.  If a newer version is available, the **Version** field shows an **Update available** tag.

7.  Click the padlock symbol next to the version and **Update available** tag.

8.  Click the **Apply Changes** button.  
    A status message (**Your gateway is being updated**) appears while the upgrade is being applied.
    A success message (**Your gateway has been successfully updated**) appears when the upgrade is
    complete.

9.  Click **Dashboard** in the navigation menu to view your gateway status.

## Delete Managed Flex Gateway

You can delete a Managed Flex Gateway using Anypoint Runtime Manager.

### Before You Begin

If there are any APIs associated with the gateway you want to delete, you must either move the APIs
to another gateway or delete the APIs. After any associated APIs are moved or deleted, follow these
steps to delete a gateway and confirm the deletion.

### Delete Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the **Managed Flex Gateway** tab.

4.  Click the name of the gateway to delete.

5.  Ensure the action menu button says **Delete Gateway**. If it says **Stop Gateway**, click the
    down arrow part of this button, and select **Delete Gateway** to change the action.

6.  Click the action menu button **Delete Gateway**.

7.  Verify that you delete the correct gateway in the confirmation dialog.

8.  Click **Yes, Delete**.  
    A status message (**Your gateway is being deleted**) appears while the action is applied. A
    success message (**Your gateway has been successfully deleted**) appears when the action is
    complete.

> [!NOTE] If you delete a gateway, you lose its configuration history.

<!-- document id=d82aa3a2c18e28a3ddcaec174afe59d1c8b3604030a3f8441d595868c6b1571e url=/mulesoft/current/en-us/gateway/1.13/gateway-managed-upgrade-delete.md -->

---
product: Omni Gateway
version: 1.13
---

# Upgrade or Delete Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade or delete a Managed Omni Gateway using Anypoint Runtime Manager.

Managed Omni Gateways are regularly auto-upgraded, depending on your Gateway release channel (LTS or
Edge). See [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.13/gateway-version-lifecycle) for more information.

You can upgrade a Managed Omni Gateway earlier than the regularly scheduled upgrade or patching
process, between the new release date and the auto-upgrade date. You can choose the time that better
suits the needs of your organization.

## Early Upgrade Managed Omni Gateway (Optional)

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the **Managed Omni Gateway** tab.

4.  Click the name of the gateway to upgrade.

5.  Click **Settings** in the navigation menu.

6.  If a newer version is available, the **Version** field shows an **Update available** tag.

7.  Click the padlock symbol next to the version and **Update available** tag.

8.  Click the **Apply Changes** button.  
    A status message (**Your gateway is being updated**) appears while the upgrade is being applied.
    A success message (**Your gateway has been successfully updated**) appears when the upgrade is
    complete.

9.  Click **Dashboard** in the navigation menu to view your gateway status.

## Delete Managed Omni Gateway

You can delete a Managed Omni Gateway using Anypoint Runtime Manager.

### Before You Begin

If there are any APIs associated with the gateway you want to delete, you must either move the APIs
to another gateway or delete the APIs. After any associated APIs are moved or deleted, follow these
steps to delete a gateway and confirm the deletion.

### Delete Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the **Managed Omni Gateway** tab.

4.  Click the name of the gateway to delete.

5.  Ensure the action menu button says **Delete Gateway**. If it says **Stop Gateway**, click the
    down arrow part of this button, and select **Delete Gateway** to change the action.

6.  Click the action menu button **Delete Gateway**.

7.  Verify that you delete the correct gateway in the confirmation dialog.

8.  Click **Yes, Delete**.  
    A status message (**Your gateway is being deleted**) appears while the action is applied. A
    success message (**Your gateway has been successfully deleted**) appears when the action is
    complete.

> [!NOTE] If you delete a gateway, you lose its configuration history.

<!-- document id=01623f2ba5eee727114674080781d938b694b324f86961a575eb46ab534b49e7 url=/mulesoft/current/en-us/gateway/latest/gateway-managed-upgrade-delete.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Upgrade or Delete Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade or delete a Managed Omni Gateway using Anypoint Runtime Manager.

Managed Omni Gateways are regularly auto-upgraded, depending on your Gateway release channel (LTS or
Edge). See [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/latest/gateway-version-lifecycle) for more information.

You can upgrade a Managed Omni Gateway earlier than the regularly scheduled upgrade or patching
process, between the new release date and the auto-upgrade date. You can choose the time that better
suits the needs of your organization.

## Early Upgrade Managed Omni Gateway (Optional)

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the **Managed Omni Gateway** tab.

4.  Click the name of the gateway to upgrade.

5.  Click **Settings** in the navigation menu.

6.  If a newer version is available, the **Version** field shows an **Update available** tag.

7.  Click the padlock symbol next to the version and **Update available** tag.

8.  Click the **Apply Changes** button.  
    A status message (**Your gateway is being updated**) appears while the upgrade is being applied.
    A success message (**Your gateway has been successfully updated**) appears when the upgrade is
    complete.

9.  Click **Dashboard** in the navigation menu to view your gateway status.

## Delete Managed Omni Gateway

You can delete a Managed Omni Gateway using Anypoint Runtime Manager.

### Before You Begin

If there are any APIs associated with the gateway you want to delete, you must either move the APIs
to another gateway or delete the APIs. After any associated APIs are moved or deleted, follow these
steps to delete a gateway and confirm the deletion.

### Delete Gateway

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the **Managed Omni Gateway** tab.

4.  Click the name of the gateway to delete.

5.  Ensure the action menu button says **Delete Gateway**. If it says **Stop Gateway**, click the
    down arrow part of this button, and select **Delete Gateway** to change the action.

6.  Click the action menu button **Delete Gateway**.

7.  Verify that you delete the correct gateway in the confirmation dialog.

8.  Click **Yes, Delete**.  
    A status message (**Your gateway is being deleted**) appears while the action is applied. A
    success message (**Your gateway has been successfully deleted**) appears when the action is
    complete.

> [!NOTE] If you delete a gateway, you lose its configuration history.

<!-- document id=3d7cdf60519a90aba327b1dc04e268bd32a46bdaafa7ddc539a938dff74bcce5 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-upgrade.md -->

---
product: Omni Gateway
version: 1.12
---

# Upgrade Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade Flex Gateway as a Linux service, in a Docker container, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.12/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Upgrade as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Upgrade in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Upgrade in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Upgrade as a Linux Service

Flex Gateway is distributed as a standard package. Use the following steps to upgrade or downgrade
Flex Gateway to either a specific version or the latest version.

To upgrade or downgrade Flex Gateway as a Linux Service:

1.  Update the list of available packages:

    ```ssh
    sudo apt update
    ```

    To list the available versions, run:

    ```ssh
    apt list -a flex-gateway
    ```

2.  Update Flex Gateway:

    - To the latest version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway
      ```

    - To a specific version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway=<version>
      ```

    - To a downgrade version:

      ```ssh
      sudo apt --only-upgrade -y --allow-downgrades install flex-gateway=<version>
      ```

3.  Restart the services:

    ```ssh
    sudo systemctl restart flex-gateway
    ```

## Upgrade in a Docker Container

The docker containers are not updated, if a new version is needed then a new container with the new
image version should be created to replace the outdated one.

The new versions of the images will be available in
[mulesoft/flex-gateway](https://hub.docker.com/r/mulesoft/flex-gateway).

## Upgrade in a Kubernetes Cluster

1.  Update charts with the respective chart repositories:

    ```ssh
    helm repo up
    ```

2.  Upgrade the release to a new version of the Helm chart by executing the following command,
    replacing example information with your own:

    ```ssh
    helm upgrade -n <namespace> <release_name> flex-gateway/flex-gateway --wait
    ```

<!-- document id=95a94ff0fc73bd76cfdfbd8ca90bf0c509a911fae20216c92dc2dfc5823b3433 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-upgrade.md -->

---
product: Omni Gateway
version: 1.9
---

# Upgrade Self-Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade Flex Gateway as a Linux service, in a Docker container, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.9/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Upgrade as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Upgrade in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Upgrade in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Upgrade as a Linux Service

Flex Gateway is distributed as a standard package. Use the following steps to upgrade or downgrade
Flex Gateway to either a specific version or the latest version.

To upgrade or downgrade Flex Gateway as a Linux Service:

1.  Update the list of available packages:

    ```ssh
    sudo apt update
    ```

    To list the available versions, run:

    ```ssh
    apt list -a flex-gateway
    ```

2.  Update Flex Gateway:

    - To the latest version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway
      ```

    - To a specific version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway=<version>
      ```

    - To a downgrade version:

      ```ssh
      sudo apt --only-upgrade -y --allow-downgrades install flex-gateway=<version>
      ```

3.  Restart the services:

    ```ssh
    sudo systemctl restart flex-gateway
    ```

## Upgrade in a Docker Container

The docker containers are not updated, if a new version is needed then a new container with the new
image version should be created to replace the outdated one.

The new versions of the images will be available in
[mulesoft/flex-gateway](https://hub.docker.com/r/mulesoft/flex-gateway).

## Upgrade in a Kubernetes Cluster

1.  Update charts with the respective chart repositories:

    ```ssh
    helm repo up
    ```

2.  Upgrade the release to a new version of the Helm chart by executing the following command,
    replacing example information with your own:

    ```ssh
    helm upgrade -n <namespace> <release_name> flex-gateway/flex-gateway --wait
    ```

<!-- document id=32ddb8e58f32549173c54ed8e4a43e3cae3897b7142d63e0381c0e5c48512f03 url=/mulesoft/current/en-us/gateway/1.13/gateway-upgrade.md -->

---
product: Omni Gateway
version: 1.13
---

# Upgrade Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade Omni Gateway as a Linux service, in a Docker container, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/1.13/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Upgrade as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Upgrade in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Upgrade in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Upgrade as a Linux Service

Omni Gateway is distributed as a standard package. Use the following steps to upgrade or downgrade
Omni Gateway to either a specific version or the latest version.

To upgrade or downgrade Omni Gateway as a Linux Service:

1.  Update the list of available packages:

    ```ssh
    sudo apt update
    ```

    To list the available versions, run:

    ```ssh
    apt list -a flex-gateway
    ```

2.  Update Omni Gateway:

    - To the latest version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway
      ```

    - To a specific version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway=<version>
      ```

    - To a downgrade version:

      ```ssh
      sudo apt --only-upgrade -y --allow-downgrades install flex-gateway=<version>
      ```

3.  Restart the services:

    ```ssh
    sudo systemctl restart flex-gateway
    ```

## Upgrade in a Docker Container

The docker containers are not updated, if a new version is needed then a new container with the new
image version should be created to replace the outdated one.

The new versions of the images will be available in
[mulesoft/flex-gateway](https://hub.docker.com/r/mulesoft/flex-gateway).

## Upgrade in a Kubernetes Cluster

1.  Update charts with the respective chart repositories:

    ```ssh
    helm repo up
    ```

2.  Upgrade the release to a new version of the Helm chart by executing the following command,
    replacing example information with your own:

    ```ssh
    helm upgrade -n <namespace> <release_name> flex-gateway/flex-gateway --wait --reuse-values
    ```

<!-- document id=fb89e15756b44f3d8afadf63aec413b8aa10f003bae48fad629c695178970119 url=/mulesoft/current/en-us/gateway/latest/gateway-upgrade.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Upgrade Self-Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can upgrade Omni Gateway as a Linux service, in a Docker container, or in a Kubernetes cluster.

<table><colgroup><col> <col> <col></colgroup><tbody><tr><td><div><div><p><span><a href="#linux"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-linux-logo.png" alt="20%" width="20%"></a></span></p></div></div></td><td><div><div><p><span><a href="#docker"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-docker-logo.png" alt="25%" width="25%"></a></span></p></div></div></td><td><div><div><p><span><a href="#kubernetes"><img src="https://docs.mulesoft.com/gateway/latest/_images/install-kubernetes-logo.png" alt="20%" width="20%"></a></span></p></div></div></td></tr><tr><td><div><div><p><a href="#linux">Upgrade as a Linux Service</a></p></div></div></td><td><div><div><p><a href="#docker">Upgrade in a Docker Container</a></p></div></div></td><td><div><div><p><a href="#kubernetes">Upgrade in a Kubernetes Cluster</a></p></div></div></td></tr></tbody></table>

## Upgrade as a Linux Service

Omni Gateway is distributed as a standard package. Use the following steps to upgrade or downgrade
Omni Gateway to either a specific version or the latest version.

To upgrade or downgrade Omni Gateway as a Linux Service:

1.  Update the list of available packages:

    ```ssh
    sudo apt update
    ```

    To list the available versions, run:

    ```ssh
    apt list -a flex-gateway
    ```

2.  Update Omni Gateway:

    - To the latest version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway
      ```

    - To a specific version:

      ```ssh
      sudo apt --only-upgrade -y install flex-gateway=<version>
      ```

    - To a downgrade version:

      ```ssh
      sudo apt --only-upgrade -y --allow-downgrades install flex-gateway=<version>
      ```

3.  Restart the services:

    ```ssh
    sudo systemctl restart flex-gateway
    ```

## Upgrade in a Docker Container

The docker containers are not updated, if a new version is needed then a new container with the new
image version should be created to replace the outdated one.

The new versions of the images will be available in
[mulesoft/flex-gateway](https://hub.docker.com/r/mulesoft/flex-gateway).

## Upgrade in a Kubernetes Cluster

1.  Update charts with the respective chart repositories:

    ```ssh
    helm repo up
    ```

2.  Upgrade the release to a new version of the Helm chart by executing the following command,
    replacing example information with your own:

    ```ssh
    helm upgrade -n <namespace> <release_name> flex-gateway/flex-gateway --wait --reuse-values
    ```

<!-- document id=f0ba79fb5106e0d3ce31060074c039aac34e81f29ad205f0e5f8075fc4e1b118 url=/mulesoft/current/en-us/gateway/1.12/flex-gateway-maintain.md -->

---
product: Omni Gateway
version: 1.12
---

# Upgrading and Maintaining Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Refer to these topics to learn about Flex Gateway release channels and Flex Gateway maintenance
tasks.

Flex Gateway Release Cadence and Support

- [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.12/flex-gateway-version-lifecycle)

Managed Flex Gateway Maintenance

- [Upgrade or Delete Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-managed-upgrade-delete)

Self-Managed Flex Gateway Maintenance

- [Upgrade Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-upgrade)

- [Delete an Instance of Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-delete)

- [Uninstall Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.12/flex-gateway-uninstall)

- [Renew Self-Managed Flex Gateway Registration](https://docs.mulesoft.com/gateway/1.12/flex-gateway-renew-certificate)

<!-- document id=a274e9f455caca56b7536bca6bf149fb23a30f34c34ff7f4ab8e321c76520a94 url=/mulesoft/current/en-us/gateway/1.9/flex-gateway-maintain.md -->

---
product: Omni Gateway
version: 1.9
---

# Upgrading and Maintaining Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Refer to these topics to learn about Flex Gateway release channels and Flex Gateway maintenance
tasks.

Flex Gateway Release Cadence and Support

- [Flex Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.9/flex-gateway-version-lifecycle)

Managed Flex Gateway Maintenance

- [Upgrade or Delete Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-managed-upgrade-delete)

Self-Managed Flex Gateway Maintenance

- [Upgrade Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-upgrade)

- [Delete an Instance of Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-delete)

- [Uninstall Self-Managed Flex Gateway](https://docs.mulesoft.com/gateway/1.9/flex-gateway-uninstall)

- [Renew Self-Managed Flex Gateway Registration](https://docs.mulesoft.com/gateway/1.9/flex-gateway-renew-certificate)

<!-- document id=162c54cd2b2fc1db5ffb9f1a38d6e84207a36b092feadd288a17084c249f4d58 url=/mulesoft/current/en-us/gateway/1.13/gateway-maintain.md -->

---
product: Omni Gateway
version: 1.13
---

# Upgrading and Maintaining Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Refer to these topics to learn about Omni Gateway release channels and Omni Gateway maintenance
tasks.

Omni Gateway Release Cadence and Support

- [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/1.13/gateway-version-lifecycle)

Managed Omni Gateway Maintenance

- [Upgrade or Delete Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-managed-upgrade-delete)

Self-Managed Omni Gateway Maintenance

- [Upgrade Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-upgrade)

- [Delete an Instance of Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-delete)

- [Uninstall Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/1.13/gateway-uninstall)

- [Renew Self-Managed Omni Gateway Registration](https://docs.mulesoft.com/gateway/1.13/gateway-renew-certificate)

<!-- document id=4d7c727919069673cdf3402f47f0260cbeda7d82687005f5bc077c120bd119cc url=/mulesoft/current/en-us/gateway/latest/gateway-maintain.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Upgrading and Maintaining Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Refer to these topics to learn about Omni Gateway release channels and Omni Gateway maintenance
tasks.

Omni Gateway Release Cadence and Support

- [Omni Gateway Version Lifecycle](https://docs.mulesoft.com/gateway/latest/gateway-version-lifecycle)

Managed Omni Gateway Maintenance

- [Upgrade or Delete Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-managed-upgrade-delete)

Self-Managed Omni Gateway Maintenance

- [Upgrade Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-upgrade)

- [Delete an Instance of Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-delete)

- [Uninstall Self-Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-uninstall)

- [Renew Self-Managed Omni Gateway Registration](https://docs.mulesoft.com/gateway/latest/gateway-renew-certificate)

<!-- document id=e07cf5260c537faeb55a5fabc470d7c5cb246abf3df3d9f45f81b985d7962b24 url=/mulesoft/current/en-us/gateway/1.12/policies-outbound-upstream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.12
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Upstream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum idle duration for a stream between the Flex Gateway and an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Upstream Idle Timeout policy lets you set a maximum idle duration between requests for a stream
between Flex Gateway and the upstream service. By applying the policy, you prevent idle connections
from consuming resources while simultaneously allowing persistent connections to remain open. The
timeout starts at the last request.

By default, all Flex Gateway API instances have an upstream idle timeout of 60 seconds. Apply the
policy to override the default timeout.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: idle-timeout-flex config: timeout: 3

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Upstream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=1bcb7301511e190d43dcb97294f13a938fa078996df8fbb8d67f3b62542a18fd url=/mulesoft/current/en-us/gateway/1.13/policies-outbound-upstream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.13
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Upstream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum idle duration for a stream between the Omni Gateway and an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-upstream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Upstream Idle Timeout policy lets you set a maximum idle duration between requests for a stream
between Omni Gateway and the upstream service. By applying the policy, you prevent idle connections
from consuming resources while simultaneously allowing persistent connections to remain open. The
timeout starts at the last request.

By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds. Apply the
policy to override the default timeout.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: idle-timeout-flex config: timeout: 3

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Upstream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=783a2f739555f8a5173c106a1d525145537fa01a0ec7f5413835b17446658630 url=/mulesoft/current/en-us/gateway/1.9/policies-outbound-upstream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.9
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Upstream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum idle duration for a stream between the Flex Gateway and an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Upstream Idle Timeout policy lets you set a maximum idle duration between requests for a stream
between Flex Gateway and the upstream service. By applying the policy, you prevent idle connections
from consuming resources while simultaneously allowing persistent connections to remain open. The
timeout starts at the last request.

By default, all Flex Gateway API instances have an upstream idle timeout of 60 seconds. Apply the
policy to override the default timeout.

## Configuring Policy Parameters

### Flex Gateway Local Mode

In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the
following policy definition and table of parameters:

\- policyRef: name: idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: idle-timeout-flex config: timeout: 3

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Upstream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Flex Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=b7622da8149d78219df943acb57c9b8225fbc8281a8cf3f9effaaf5be4624bdf url=/mulesoft/current/en-us/gateway/latest/policies-outbound-upstream-idle-timeout.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: basic authentication, api gateway, flex gateway, gateway, policy
---

# Upstream Idle Timeout Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Stream Idle Timeout</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Sets the maximum idle duration for a stream between the Omni Gateway and an upstream service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.9.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-upstream-idle-timeout-release-notes">Stream Idle Timeout</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>504 - Upstream request timeout</p></td></tr></tbody></table>

## Summary

The Upstream Idle Timeout policy lets you set a maximum idle duration between requests for a stream
between Omni Gateway and the upstream service. By applying the policy, you prevent idle connections
from consuming resources while simultaneously allowing persistent connections to remain open. The
timeout starts at the last request.

By default, all Omni Gateway API instances have an upstream idle timeout of 60 seconds. Apply the
policy to override the default timeout.

This policy overrides every other Upstream Connection Idle Timeout configuration for the API
instance you apply it to, whether the policy value is higher or lower. To change the gateway-level
timeout, see [Configure Timeouts for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-timeout) or
[Configuring Timeouts in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-timeout).

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: idle-timeout-flex config: timeout: number // REQUIRED

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>timeout</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>60</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: idle-timeout-flex config: timeout: 3

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Upstream idle timeout</p></div></div></td><td><div><div><p>Time in seconds before Omni Gateway closes the connection.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

<!-- document id=315e45be07525c5aecdb850f952133d8818c34a04971fa011d36abc113b2f370 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-uc1.md -->

---
product: Omni Gateway
version: 1.12
---

# Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case one covers all patterns of a scenario in which a trusted organization’s API is exposed to a
trusted organization’s API consumer.

## Pattern 1: Organization Internal API Exposed to an Organization Internal Consumer

Pattern examples:

- A sales application accesses a customer service API in which both sales and customer service are
  internal areas of the customer organization

- A call center application calls the API exposed by the customer domain to retrieve customer
  information

- A mobile bank calls customer and account services to display the account overview screen to the
  end consumer

### Pattern 1A: Organization Internal API Exposed to an Organization Internal Consumer that Uses the Same VPC or Network

In this use case pattern, both services are available on the same infrastructure, such as the same
public cloud VPC, datacenter, or Kubernetes cluster. You can deploy Flex Gateway as either a sidecar
or a standalone gateway.

![For both standalone and sidecar mode, Flex Gateway and the APIs are in the same internal network.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-1a.png)

The following diagram shows the physical implementation of a standalone Flex Gateway running in
Connected Mode. A network policy (Netpol) permits ingress access only from Flex Gateway. You can
configure the consumer application in the same or different namespace from Flex Gateway and the
provider services.

![A more detailed view of UC1 contains load balancers and Netpol protection](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-1a-physical.png)

When the API provider is located in a different Kubernetes cluster from Flex Gateway and the
consumer application, you can do either of the following:

- Deploy a Flex Gateway runtime on each of the clusters, as in Pattern 1B.

- Establish network restrictions in the secure channel between clusters and deploy Flex Gateway in
  only one of them, as shown in the following diagram. The second cluster only allows connections
  from a Flex Gateway that acts as an ingress controller.

![A detailed view of pattern 1A, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-1b-separate-clusters.png)

### Pattern 1B: Organization Internal API Exposed to an Organization Internal Consumer that Uses a Different VPC or Network

In this pattern, the API provider is isolated from the API consumer. However, there is a secure
communication channel available between the two networks.

You deploy Flex Gateway as an ingress behind a firewall because traffic is considered external to
the location of the provider. Flex Gateway receives and processes the incoming traffic.

You can use Flex Gateway to terminate the TLS or mTLS connection if required.

![Information travels from a trusted network to the internal network that contains Flex Gateway.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-1b.png)

The following diagram shows the physical implementation on Kubernetes.

![The previous networks are now Kubernetes clusters and there are load balancers that separate the APIs from Flex Gateway.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-1b-physical.png)

## Pattern 2: Organization Internal API exposed an Organization External Consumer

In pattern two, the organization-owned API is isolated from the organization-owned API consumer, for
example, in a package delivery tracking API that is accessed from a user interface. The consumer can
access the exposed API only via the internet. In this use case, you deploy Flex Gateway as an
ingress.

![Consumer application requests pass through the internet and a firewall before reaching Flex Gateway.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-2.png)

This pattern is similar to Pattern 1B. However, in this pattern, traffic arrives from the public
internet instead of from a private channel. Because traffic is coming from the public internet, you
must add additional controls to strengthen communication security before reaching Flex Gateway.

The following diagram shows the physical implementation of a scenario in which an organization’s
internal API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now Kubernetes clusters, there are load balancers separating the APIs from Flex Gateway, and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-2-physical.png)

## Pattern 3: Organization External API Exposed to an Organization Internal Consumer

In pattern three, the API Consumer is in the same network as Flex Gateway. You can use Flex Gateway
to monitor, control, and enrich the flows to external services. For example, Flex Gateway can
provide rate limiting for the external access traffic, or metrics and analytics tracking for this
external service connection.

Pattern examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

For pattern three, you deploy Flex Gateway as a standalone gateway that acts as an egress container.

![Flex Gateway is deployed as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which an organization’s
external API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now kubernetes clusters. There are load balancers that separate the APIs from Flex Gateway and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-3-physical.png)

## Pattern 4: Organization External API Exposed to an Organization External Consumer

In pattern four, Flex Gateway acts as an intermediary between two organizations' external entities,
for example, when an organization’s WorkDay instance (SaaS service) accesses the organization’s
ServiceNow instance (SaaS service). In this pattern, Flex Gateway runs as an ingress and egress that
applies secured communication and policy enforcement.

![Flex Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
organization’s API is exposed to an external organization’s consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming organization’s external mTLS connection.

![A detailed view of pattern four, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-4-physical.png)

## See Also

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4)

<!-- document id=d1351cf0bdbf5d092d091f812b8c4c254907a2cd198206ff82120bfc9972b273 url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-uc1.md -->

---
product: Omni Gateway
version: 1.13
---

# Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case one covers all patterns of a scenario in which a trusted organization’s API is exposed to a
trusted organization’s API consumer.

## Pattern 1: Organization Internal API Exposed to an Organization Internal Consumer

Pattern examples:

- A sales application accesses a customer service API in which both sales and customer service are
  internal areas of the customer organization

- A call center application calls the API exposed by the customer domain to retrieve customer
  information

- A mobile bank calls customer and account services to display the account overview screen to the
  end consumer

### Pattern 1A: Organization Internal API Exposed to an Organization Internal Consumer that Uses the Same VPC or Network

In this use case pattern, both services are available on the same infrastructure, such as the same
public cloud VPC, datacenter, or Kubernetes cluster. You can deploy Omni Gateway as either a sidecar
or a standalone gateway.

![For both standalone and sidecar mode, Omni Gateway and the APIs are in the same internal network.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-1a.png)

The following diagram shows the physical implementation of a standalone Omni Gateway running in
Connected Mode. A network policy (Netpol) permits ingress access only from Omni Gateway. You can
configure the consumer application in the same or different namespace from Omni Gateway and the
provider services.

![A more detailed view of UC1 contains load balancers and Netpol protection](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-1a-physical.png)

When the API provider is located in a different Kubernetes cluster from Omni Gateway and the
consumer application, you can do either of the following:

- Deploy an Omni Gateway runtime on each of the clusters, as in Pattern 1B.

- Establish network restrictions in the secure channel between clusters and deploy Omni Gateway in
  only one of them, as shown in the following diagram. The second cluster only allows connections
  from an Omni Gateway that acts as an ingress controller.

![A detailed view of pattern 1A, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-1b-separate-clusters.png)

### Pattern 1B: Organization Internal API Exposed to an Organization Internal Consumer that Uses a Different VPC or Network

In this pattern, the API provider is isolated from the API consumer. However, there is a secure
communication channel available between the two networks.

You deploy Omni Gateway as an ingress behind a firewall because traffic is considered external to
the location of the provider. Omni Gateway receives and processes the incoming traffic.

You can use Omni Gateway to terminate the TLS or mTLS connection if required.

![Information travels from a trusted network to the internal network that contains Omni Gateway.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-1b.png)

The following diagram shows the physical implementation on Kubernetes.

![The previous networks are now Kubernetes clusters and there are load balancers that separate the APIs from Omni Gateway.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-1b-physical.png)

## Pattern 2: Organization Internal API exposed an Organization External Consumer

In pattern two, the organization-owned API is isolated from the organization-owned API consumer, for
example, in a package delivery tracking API that is accessed from a user interface. The consumer can
access the exposed API only via the internet. In this use case, you deploy Omni Gateway as an
ingress.

![Consumer application requests pass through the internet and a firewall before reaching Omni Gateway.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-2.png)

This pattern is similar to Pattern 1B. However, in this pattern, traffic arrives from the public
internet instead of from a private channel. Because traffic is coming from the public internet, you
must add additional controls to strengthen communication security before reaching Omni Gateway.

The following diagram shows the physical implementation of a scenario in which an organization’s
internal API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now Kubernetes clusters, there are load balancers separating the APIs from Omni Gateway, and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-2-physical.png)

## Pattern 3: Organization External API Exposed to an Organization Internal Consumer

In pattern three, the API Consumer is in the same network as Omni Gateway. You can use Omni Gateway
to monitor, control, and enrich the flows to external services. For example, Omni Gateway can
provide rate limiting for the external access traffic, or metrics and analytics tracking for this
external service connection.

Pattern examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

For pattern three, you deploy Omni Gateway as a standalone gateway that acts as an egress container.

![Omni Gateway is deployed as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which an organization’s
external API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now kubernetes clusters. There are load balancers that separate the APIs from Omni Gateway and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-3-physical.png)

## Pattern 4: Organization External API Exposed to an Organization External Consumer

In pattern four, Omni Gateway acts as an intermediary between two organizations' external entities,
for example, when an organization’s WorkDay instance (SaaS service) accesses the organization’s
ServiceNow instance (SaaS service). In this pattern, Omni Gateway runs as an ingress and egress that
applies secured communication and policy enforcement.

![Omni Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
organization’s API is exposed to an external organization’s consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming organization’s external mTLS connection.

![A detailed view of pattern four, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-4-physical.png)

## See Also

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4)

<!-- document id=900f734333c2796618e0a45a5638276090962136cf90e52ea3b81ffa6f6180da url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-uc1.md -->

---
product: Omni Gateway
version: 1.9
---

# Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case one covers all patterns of a scenario in which a trusted organization’s API is exposed to a
trusted organization’s API consumer.

## Pattern 1: Organization Internal API Exposed to an Organization Internal Consumer

Pattern examples:

- A sales application accesses a customer service API in which both sales and customer service are
  internal areas of the customer organization

- A call center application calls the API exposed by the customer domain to retrieve customer
  information

- A mobile bank calls customer and account services to display the account overview screen to the
  end consumer

### Pattern 1A: Organization Internal API Exposed to an Organization Internal Consumer that Uses the Same VPC or Network

In this use case pattern, both services are available on the same infrastructure, such as the same
public cloud VPC, datacenter, or Kubernetes cluster. You can deploy Flex Gateway as either a sidecar
or a standalone gateway.

![For both standalone and sidecar mode, Flex Gateway and the APIs are in the same internal network.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-1a.png)

The following diagram shows the physical implementation of a standalone Flex Gateway running in
Connected Mode. A network policy (Netpol) permits ingress access only from Flex Gateway. You can
configure the consumer application in the same or different namespace from Flex Gateway and the
provider services.

![A more detailed view of UC1 contains load balancers and Netpol protection](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-1a-physical.png)

When the API provider is located in a different Kubernetes cluster from Flex Gateway and the
consumer application, you can do either of the following:

- Deploy a Flex Gateway runtime on each of the clusters, as in Pattern 1B.

- Establish network restrictions in the secure channel between clusters and deploy Flex Gateway in
  only one of them, as shown in the following diagram. The second cluster only allows connections
  from a Flex Gateway that acts as an ingress controller.

![A detailed view of pattern 1A, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-1b-separate-clusters.png)

### Pattern 1B: Organization Internal API Exposed to an Organization Internal Consumer that Uses a Different VPC or Network

In this pattern, the API provider is isolated from the API consumer. However, there is a secure
communication channel available between the two networks.

You deploy Flex Gateway as an ingress behind a firewall because traffic is considered external to
the location of the provider. Flex Gateway receives and processes the incoming traffic.

You can use Flex Gateway to terminate the TLS or mTLS connection if required.

![Information travels from a trusted network to the internal network that contains Flex Gateway.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-1b.png)

The following diagram shows the physical implementation on Kubernetes.

![The previous networks are now Kubernetes clusters and there are load balancers that separate the APIs from Flex Gateway.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-1b-physical.png)

## Pattern 2: Organization Internal API exposed an Organization External Consumer

In pattern two, the organization-owned API is isolated from the organization-owned API consumer, for
example, in a package delivery tracking API that is accessed from a user interface. The consumer can
access the exposed API only via the internet. In this use case, you deploy Flex Gateway as an
ingress.

![Consumer application requests pass through the internet and a firewall before reaching Flex Gateway.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-2.png)

This pattern is similar to Pattern 1B. However, in this pattern, traffic arrives from the public
internet instead of from a private channel. Because traffic is coming from the public internet, you
must add additional controls to strengthen communication security before reaching Flex Gateway.

The following diagram shows the physical implementation of a scenario in which an organization’s
internal API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now Kubernetes clusters, there are load balancers separating the APIs from Flex Gateway, and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-2-physical.png)

## Pattern 3: Organization External API Exposed to an Organization Internal Consumer

In pattern three, the API Consumer is in the same network as Flex Gateway. You can use Flex Gateway
to monitor, control, and enrich the flows to external services. For example, Flex Gateway can
provide rate limiting for the external access traffic, or metrics and analytics tracking for this
external service connection.

Pattern examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

For pattern three, you deploy Flex Gateway as a standalone gateway that acts as an egress container.

![Flex Gateway is deployed as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which an organization’s
external API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now kubernetes clusters. There are load balancers that separate the APIs from Flex Gateway and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-3-physical.png)

## Pattern 4: Organization External API Exposed to an Organization External Consumer

In pattern four, Flex Gateway acts as an intermediary between two organizations' external entities,
for example, when an organization’s WorkDay instance (SaaS service) accesses the organization’s
ServiceNow instance (SaaS service). In this pattern, Flex Gateway runs as an ingress and egress that
applies secured communication and policy enforcement.

![Flex Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
organization’s API is exposed to an external organization’s consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming organization’s external mTLS connection.

![A detailed view of pattern four, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-4-physical.png)

## See Also

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4)

<!-- document id=a9bdc28db0c60d4dae334b8825e1b878a0fb82a128526032bb3c7b64c22a4160 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-uc1.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case one covers all patterns of a scenario in which a trusted organization’s API is exposed to a
trusted organization’s API consumer.

## Pattern 1: Organization Internal API Exposed to an Organization Internal Consumer

Pattern examples:

- A sales application accesses a customer service API in which both sales and customer service are
  internal areas of the customer organization

- A call center application calls the API exposed by the customer domain to retrieve customer
  information

- A mobile bank calls customer and account services to display the account overview screen to the
  end consumer

### Pattern 1A: Organization Internal API Exposed to an Organization Internal Consumer that Uses the Same VPC or Network

In this use case pattern, both services are available on the same infrastructure, such as the same
public cloud VPC, datacenter, or Kubernetes cluster. You can deploy Omni Gateway as either a sidecar
or a standalone gateway.

![For both standalone and sidecar mode, Omni Gateway and the APIs are in the same internal network.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-1a.png)

The following diagram shows the physical implementation of a standalone Omni Gateway running in
Connected Mode. A network policy (Netpol) permits ingress access only from Omni Gateway. You can
configure the consumer application in the same or different namespace from Omni Gateway and the
provider services.

![A more detailed view of UC1 contains load balancers and Netpol protection](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-1a-physical.png)

When the API provider is located in a different Kubernetes cluster from Omni Gateway and the
consumer application, you can do either of the following:

- Deploy an Omni Gateway runtime on each of the clusters, as in Pattern 1B.

- Establish network restrictions in the secure channel between clusters and deploy Omni Gateway in
  only one of them, as shown in the following diagram. The second cluster only allows connections
  from an Omni Gateway that acts as an ingress controller.

![A detailed view of pattern 1A, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-1b-separate-clusters.png)

### Pattern 1B: Organization Internal API Exposed to an Organization Internal Consumer that Uses a Different VPC or Network

In this pattern, the API provider is isolated from the API consumer. However, there is a secure
communication channel available between the two networks.

You deploy Omni Gateway as an ingress behind a firewall because traffic is considered external to
the location of the provider. Omni Gateway receives and processes the incoming traffic.

You can use Omni Gateway to terminate the TLS or mTLS connection if required.

![Information travels from a trusted network to the internal network that contains Omni Gateway.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-1b.png)

The following diagram shows the physical implementation on Kubernetes.

![The previous networks are now Kubernetes clusters and there are load balancers that separate the APIs from Omni Gateway.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-1b-physical.png)

## Pattern 2: Organization Internal API exposed an Organization External Consumer

In pattern two, the organization-owned API is isolated from the organization-owned API consumer, for
example, in a package delivery tracking API that is accessed from a user interface. The consumer can
access the exposed API only via the internet. In this use case, you deploy Omni Gateway as an
ingress.

![Consumer application requests pass through the internet and a firewall before reaching Omni Gateway.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-2.png)

This pattern is similar to Pattern 1B. However, in this pattern, traffic arrives from the public
internet instead of from a private channel. Because traffic is coming from the public internet, you
must add additional controls to strengthen communication security before reaching Omni Gateway.

The following diagram shows the physical implementation of a scenario in which an organization’s
internal API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now Kubernetes clusters, there are load balancers separating the APIs from Omni Gateway, and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-2-physical.png)

## Pattern 3: Organization External API Exposed to an Organization Internal Consumer

In pattern three, the API Consumer is in the same network as Omni Gateway. You can use Omni Gateway
to monitor, control, and enrich the flows to external services. For example, Omni Gateway can
provide rate limiting for the external access traffic, or metrics and analytics tracking for this
external service connection.

Pattern examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

For pattern three, you deploy Omni Gateway as a standalone gateway that acts as an egress container.

![Omni Gateway is deployed as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which an organization’s
external API is exposed to an organization’s internal consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![The previous networks are now kubernetes clusters. There are load balancers that separate the APIs from Omni Gateway and mTLS connections to external networks.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-3-physical.png)

## Pattern 4: Organization External API Exposed to an Organization External Consumer

In pattern four, Omni Gateway acts as an intermediary between two organizations' external entities,
for example, when an organization’s WorkDay instance (SaaS service) accesses the organization’s
ServiceNow instance (SaaS service). In this pattern, Omni Gateway runs as an ingress and egress that
applies secured communication and policy enforcement.

![Omni Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
organization’s API is exposed to an external organization’s consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming organization’s external mTLS connection.

![A detailed view of pattern four, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-4-physical.png)

## See Also

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4)

<!-- document id=261f826a7d71b5863ce95195ed6cde1066a730918f15f7b961c6ab532d72562e url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-uc2.md -->

---
product: Omni Gateway
version: 1.12
---

# Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case two covers all patterns of a scenario in which an organization-owned API is exposed to a
non-organization-owned API consumer; for example, when a user makes a request to your public-facing
API.

## Pattern 5: Organization Internal API exposed to a Non-Organization External Consumer

In pattern five, the infrastructure of the organization-owned API is isolated from the API consumer.
The consumer can access the exposed API only via the internet. In this use case, you deploy Flex
Gateway as an ingress.

![Consumer application requests pass through the internet and a firewall before reaching Flex Gateway.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-2.png)

The following diagram shows the physical implementation of a scenario in which an organization-owned
internal API is exposed to a non-organization-owned external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern five, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-2-p-5-physical.png)

## Pattern 6: Organization External API exposed to a Non-Organization External Consumer

In pattern six, Flex Gateway acts as an intermediary between two external network entities. Flex
Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Flex Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an organization
external API is exposed to an non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the external mTLS connections.

![A detailed view of pattern six, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-2-p-6-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4)

<!-- document id=02b4bb786dd310a1d712719b022f6006b784134470dc782546122e3a1cf96f6c url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-uc2.md -->

---
product: Omni Gateway
version: 1.13
---

# Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case two covers all patterns of a scenario in which an organization-owned API is exposed to a
non-organization-owned API consumer; for example, when a user makes a request to your public-facing
API.

## Pattern 5: Organization Internal API exposed to a Non-Organization External Consumer

In pattern five, the infrastructure of the organization-owned API is isolated from the API consumer.
The consumer can access the exposed API only via the internet. In this use case, you deploy Omni
Gateway as an ingress.

![Consumer application requests pass through the internet and a firewall before reaching Omni Gateway.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-2.png)

The following diagram shows the physical implementation of a scenario in which an organization-owned
internal API is exposed to a non-organization-owned external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern five, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-2-p-5-physical.png)

## Pattern 6: Organization External API exposed to a Non-Organization External Consumer

In pattern six, Omni Gateway acts as an intermediary between two external network entities. Omni
Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Omni Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an organization
external API is exposed to an non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the external mTLS connections.

![A detailed view of pattern six, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-2-p-6-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4)

<!-- document id=d608f8179575ed323d92b462134a98685a577ae251d7cc5963c10b32ad74c918 url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-uc2.md -->

---
product: Omni Gateway
version: 1.9
---

# Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case two covers all patterns of a scenario in which an organization-owned API is exposed to a
non-organization-owned API consumer; for example, when a user makes a request to your public-facing
API.

## Pattern 5: Organization Internal API exposed to a Non-Organization External Consumer

In pattern five, the infrastructure of the organization-owned API is isolated from the API consumer.
The consumer can access the exposed API only via the internet. In this use case, you deploy Flex
Gateway as an ingress.

![Consumer application requests pass through the internet and a firewall before reaching Flex Gateway.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-2.png)

The following diagram shows the physical implementation of a scenario in which an organization-owned
internal API is exposed to a non-organization-owned external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern five, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-2-p-5-physical.png)

## Pattern 6: Organization External API exposed to a Non-Organization External Consumer

In pattern six, Flex Gateway acts as an intermediary between two external network entities. Flex
Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Flex Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an organization
external API is exposed to an non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the external mTLS connections.

![A detailed view of pattern six, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-2-p-6-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4)

<!-- document id=8b45d28f9b8cb47b8d9ccc52013bee33b252b719f4aa894d15102d8303696a94 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-uc2.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case two covers all patterns of a scenario in which an organization-owned API is exposed to a
non-organization-owned API consumer; for example, when a user makes a request to your public-facing
API.

## Pattern 5: Organization Internal API exposed to a Non-Organization External Consumer

In pattern five, the infrastructure of the organization-owned API is isolated from the API consumer.
The consumer can access the exposed API only via the internet. In this use case, you deploy Omni
Gateway as an ingress.

![Consumer application requests pass through the internet and a firewall before reaching Omni Gateway.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-2.png)

The following diagram shows the physical implementation of a scenario in which an organization-owned
internal API is exposed to a non-organization-owned external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern five, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-2-p-5-physical.png)

## Pattern 6: Organization External API exposed to a Non-Organization External Consumer

In pattern six, Omni Gateway acts as an intermediary between two external network entities. Omni
Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Omni Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an organization
external API is exposed to an non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the external mTLS connections.

![A detailed view of pattern six, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-2-p-6-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4)

<!-- document id=79cd99c75a3ea5469e6fc6107e37527ac30b0421594e1ca402f63c4d1b21215e url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-uc3.md -->

---
product: Omni Gateway
version: 1.12
---

# Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case three covers all patterns of a scenario in which a non-organization-owned API is exposed to
an organization-owned API consumer.

Use case examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

## Pattern 7: Non-Organization External API exposed to an Organization Internal Consumer

In pattern seven, you deploy Flex Gateway as an egress. You can use Flex Gateway to monitor,
control, and enrich the flows to external services. Additionally, you can rate limit external access
and track metrics and analytics.

![Flex Gateway acts as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to an organization internal consumer on Kubernetes. The diagram assumes that
the firewall terminates the incoming non-organization external mTLS connection.

![A detailed view of pattern](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-3-p-7-physical.png)

## Pattern 8: Non-Organization External API exposed to an Organization External Consumer

In pattern eight, Flex Gateway acts as an intermediary between two organization external entities.
Flex Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Flex Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
non-organization API is exposed to an organization external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern eight, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-3-p-8-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc4)

<!-- document id=f8adefd145f6401f48f0a9a481c7535418946763c7140e378b5eee67bae2d511 url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-uc3.md -->

---
product: Omni Gateway
version: 1.13
---

# Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case three covers all patterns of a scenario in which a non-organization-owned API is exposed to
an organization-owned API consumer.

Use case examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

## Pattern 7: Non-Organization External API exposed to an Organization Internal Consumer

In pattern seven, you deploy Omni Gateway as an egress. You can use Omni Gateway to monitor,
control, and enrich the flows to external services. Additionally, you can rate limit external access
and track metrics and analytics.

![Omni Gateway acts as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to an organization internal consumer on Kubernetes. The diagram assumes that
the firewall terminates the incoming non-organization external mTLS connection.

![A detailed view of pattern](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-3-p-7-physical.png)

## Pattern 8: Non-Organization External API exposed to an Organization External Consumer

In pattern eight, Omni Gateway acts as an intermediary between two organization external entities.
Omni Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Omni Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
non-organization API is exposed to an organization external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern eight, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-3-p-8-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc4)

<!-- document id=eddbdfebc7c91c42cdf3659a36be33c3a8a9d35b064541afd22c5523e6db3138 url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-uc3.md -->

---
product: Omni Gateway
version: 1.9
---

# Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case three covers all patterns of a scenario in which a non-organization-owned API is exposed to
an organization-owned API consumer.

Use case examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

## Pattern 7: Non-Organization External API exposed to an Organization Internal Consumer

In pattern seven, you deploy Flex Gateway as an egress. You can use Flex Gateway to monitor,
control, and enrich the flows to external services. Additionally, you can rate limit external access
and track metrics and analytics.

![Flex Gateway acts as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to an organization internal consumer on Kubernetes. The diagram assumes that
the firewall terminates the incoming non-organization external mTLS connection.

![A detailed view of pattern](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-3-p-7-physical.png)

## Pattern 8: Non-Organization External API exposed to an Organization External Consumer

In pattern eight, Flex Gateway acts as an intermediary between two organization external entities.
Flex Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Flex Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
non-organization API is exposed to an organization external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern eight, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-3-p-8-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc4)

<!-- document id=86e22bab268e4eb584700e5cfa0f00d2ace186f5f6c65f0bf0ecc52fe58cb407 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-uc3.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case three covers all patterns of a scenario in which a non-organization-owned API is exposed to
an organization-owned API consumer.

Use case examples:

- A payments service must obtain exchange rates from an external service provider.

- An internal API Consumer accesses the organization’s external ServiceNow instance (SaaS service).

## Pattern 7: Non-Organization External API exposed to an Organization Internal Consumer

In pattern seven, you deploy Omni Gateway as an egress. You can use Omni Gateway to monitor,
control, and enrich the flows to external services. Additionally, you can rate limit external access
and track metrics and analytics.

![Omni Gateway acts as an egress to monitor incoming traffic from the external API.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-3.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to an organization internal consumer on Kubernetes. The diagram assumes that
the firewall terminates the incoming non-organization external mTLS connection.

![A detailed view of pattern](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-3-p-7-physical.png)

## Pattern 8: Non-Organization External API exposed to an Organization External Consumer

In pattern eight, Omni Gateway acts as an intermediary between two organization external entities.
Omni Gateway runs as an ingress and egress that applies secure communication and policy enforcement.

![Omni Gateway acts as an intermediary between an external application and external API.](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which an external
non-organization API is exposed to an organization external consumer on Kubernetes. The diagram
assumes that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern eight, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-3-p-8-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2)

- [Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc4)

<!-- document id=dbd4b949d39d3a817a4f948e9ab68e37757831aafaa90ba66b236da6256a0f53 url=/mulesoft/current/en-us/gateway/1.12/flex-architecture-uc4.md -->

---
product: Omni Gateway
version: 1.12
---

# Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case four has one pattern that supports the scenario in which a non-organization API is exposed
to a non-organization API consumer.

## Pattern 9: Non-Organization External API exposed to a Non-Organization External Consumer

In pattern nine, Flex Gateway acts as an intermediary between two external entities; for example,
when an external customer consumes a travel information service offered by an external airline.

![Flex Gateway acts as an intermediary between an external application and external API](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to a non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern nine, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.12/_images/ad-uc-4-p-9-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.12/flex-architecture-uc3)

<!-- document id=82fba413b9d2c642e33342d5f28f6451d13a2a972df17499fd2303a7536c04a6 url=/mulesoft/current/en-us/gateway/1.13/gateway-architecture-uc4.md -->

---
product: Omni Gateway
version: 1.13
---

# Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case four has one pattern that supports the scenario in which a non-organization API is exposed
to a non-organization API consumer.

## Pattern 9: Non-Organization External API exposed to a Non-Organization External Consumer

In pattern nine, Omni Gateway acts as an intermediary between two external entities; for example,
when an external customer consumes a travel information service offered by an external airline.

![Omni Gateway acts as an intermediary between an external application and external API](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to a non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern nine, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/1.13/_images/ad-uc-4-p-9-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-uc3)

<!-- document id=412be9ac5f188b4e2a2c0e77b038ac0bde4100be84e48d10cfec31374939008c url=/mulesoft/current/en-us/gateway/1.9/flex-architecture-uc4.md -->

---
product: Omni Gateway
version: 1.9
---

# Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case four has one pattern that supports the scenario in which a non-organization API is exposed
to a non-organization API consumer.

## Pattern 9: Non-Organization External API exposed to a Non-Organization External Consumer

In pattern nine, Flex Gateway acts as an intermediary between two external entities; for example,
when an external customer consumes a travel information service offered by an external airline.

![Flex Gateway acts as an intermediary between an external application and external API](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to a non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern nine, which contains the necessary services to support Flex Gateway](/mulesoft/current/en-us/gateway/1.9/_images/ad-uc-4-p-9-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/1.9/flex-architecture-uc3)

<!-- document id=11ff7467dfb07ab30759263f540b25ddca84e0ccd4069a4e8c83b44edd666263 url=/mulesoft/current/en-us/gateway/latest/gateway-architecture-uc4.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Use Case 4: Non-Organization-Owned API Exposed to a Non-Organization-Owned API Consumer

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use case four has one pattern that supports the scenario in which a non-organization API is exposed
to a non-organization API consumer.

## Pattern 9: Non-Organization External API exposed to a Non-Organization External Consumer

In pattern nine, Omni Gateway acts as an intermediary between two external entities; for example,
when an external customer consumes a travel information service offered by an external airline.

![Omni Gateway acts as an intermediary between an external application and external API](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-1-p-4.png)

The following diagram shows the physical implementation of a scenario in which a non-organization
external API is exposed to a non-organization external consumer on Kubernetes. The diagram assumes
that the firewall terminates the incoming external mTLS connection.

![A detailed view of pattern nine, which contains the necessary services to support Omni Gateway](/mulesoft/current/en-us/gateway/latest/_images/ad-uc-4-p-9-physical.png)

## See Also

- [Use Case 1: Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc1)

- [Use Case 2: Organization-Owned API Exposed to a Non-Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc2)

- [Use Case 3: Non-Organization-Owned API Exposed to an Organization-Owned API Consumer](https://docs.mulesoft.com/gateway/latest/gateway-architecture-uc3)

<!-- document id=0966c3d727dbcd3bf33964166fd44832e7691f05e5a38d82fe45c997b5a5d0e5 url=/mulesoft/current/en-us/gateway/1.12/flex-use-api-alerts.md -->

---
product: Omni Gateway
version: 1.12
---

# Using Flex Gateway API Alerts

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using API alerts, you can add and configure email notifications that flag unusual API behavior, such
as:

- An API response time over 60 seconds

- More than 1000 API requests in 30 seconds

See [Add API Alerts](#add-api-alerts) below.

## Types of API Alerts

Add any of the following alerts to notify you of the condition described:

- Total Request Count: Users request access to the API more times than allowed during a specified
  time. Specify time interval values from 1 through 999999999. To prevent data bursts, intervals are
  implemented as sliding windows instead of as absolute minute boundaries.

- Average Response Time: The response time of the API exceeds a specified timeout period.

- Response Codes: Upon receiving a request, the API returns an HTTP code of 400, 401, 403, 404, 408,
  500, 502, or 503 or a custom three-digit response.

- Policy Violation: An infraction of a specified policy governing the API occurs.

## How API Alerts Work

API alerts are triggered only when:

- The API state changes

  Note that the first occurrence of a state change might go undetected if a newly created alert does
  not include defined states.

- The alert conditions are met for the specified period of time

  For example, if an alert is configured to trigger when an API returns an HTTP code of 500 five or
  more times within a 10-minute period, it does not trigger if the API returns a code of 500 only
  once within that 10-minute period.

When configuring an API alert, you can select business group users and users outside your
organization to receive email notifications about the alert. Notifications include information about
events that trigger alerts as specified by severity level.

> [!NOTE] API Alerts are sent from `no-reply@mulesoft.com`. This cannot be customized.

- The first email describes the alert:

  `Your API, CesarDemoAPI - Basic:151 (Environment: "NewOne"), has received greater than 2 requests within 1 consecutive periods of 1 minutes.`

- Another email notifies you when the alert is resolved:

  `Your API Version, jsonplaceholderapi - 1.0.development, is no longer in an alert state. The number of policy violations was not greater than 1 in the last 1 consecutive periods of 1 minutes.`

After the first set of two notification emails is sent, API Manager stops listening for alerts until
the next alert period begins. This technique prevents repeated notification emails.

## Before You Begin

To view and delete alerts, ensure that you have:

- **Manage Alerts** permission to view and delete API alerts.

- **View Alerts** permission for view-only access to alerts.

## Add API Alerts

To track and manage APIs, you can add one or more API alerts to your API instances. Add different
[types of alerts](#types-of-api-alerts) based on your requirements.

The following table explains the number of active alerts per API instance:

<table><colgroup><col> <col></colgroup><thead><tr><th>Pricing Package</th><th>Active Alerts</th></tr></thead><tbody><tr><td><p>Anypoint Integration Starter</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Anypoint Integration Advanced</p></td><td><p>Up to 10</p></td></tr><tr><td><p>Gold Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Platinum Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Titanium Subscription</p></td><td><p>Up to 10</p></td></tr></tbody></table>

All subscriptions enable you to have as many non-active alerts as needed.

Pausing or deleting an active alert enables you to create new alerts if you have reached the maximum
number of active alerts.

Alerts are enabled by default when created. This setting cannot be modified.

> [!NOTE] Alerts cannot be added to API instances protected by
> [automated policies](https://docs.mulesoft.com/gateway/latest/policies-automated-overview).

To add an API alert:

1.  Navigate to **API Manager** > **API Instances** and click the API instance for which you want to
    add an alert.

2.  From the left navigation pane, select **Alerts** > **New alert**.

3.  Specify values for the displayed alert options:

    - **Name**:

      Type an alert name, for example, `trial-alert`. You can delete an alert anytime if not
      required.

    - **Severity**:

      Select a severity for the alert:

      - **Info**

        Assign to alerts that do not require immediate attention when triggered. This severity
        indicates that the metric should be passively monitored.

      - **Warning**

        Assign to alerts that require prompt attention when triggered. This severity indicates an
        alert should be closely monitored.

      - **Critical**

        Assign to alerts that require immediate attention when triggered. This severity indicates an
        alert should receive an immediate response.

4.  Specify the alert conditions:

    - **Metric**

      Condition that triggers the alert.

    - **Logic**

      When the alert is triggered, based on the occurrence rate defined in the **When number of
      occurrences are** and **For at least \[number of\] minutes** fields. You can select a maximum
      of ten response codes for alert conditions.

5.  Configure the email notification:

    - **Subject**

      Subject of the alert email to send when the alert is triggered. The subject can include
      variables. See [Variable Definitions](#alert-variables).

    - **Message**

      Body text for the email to send when the alert is triggered. The message body can include
      variables. See [Variable Definitions](#alert-variables).

    - **Recipients**

      Recipients of the alert email. You can select up to 20 platform user IDs and enter up to 20
      email addresses.

6.  Click **Create**.

Alerts appear as **Pending** when they are created. After the API receives traffic, the alert
changes to a state of **OK**. Depending on the value, the alert transitions to **OK** or
**Alerting**.

### Alert Email Template

You can use the following variables in the **Subject** and **Message** fields for basic email
alerts.

For the description of each variable, see [Variable Definitions](#alert-variables).

<table><caption>Table 1. Variables for Alerts</caption> <colgroup><col> <col></colgroup><thead><tr><th>Alert</th><th>Applicable Variables</th></tr></thead><tbody><tr><td><p><strong>Total Request Count</strong></p></td><td rowspan="4"><div><div><ul><li><p><code>${severity}</code></p></li><li><p><code>${operator}</code></p></li><li><p><code>${threshold}</code></p></li><li><p><code>${period}</code></p></li><li><p><code>${value}</code></p></li><li><p><code>${condition}</code></p></li><li><p><code>${organization}</code></p></li><li><p><code>${environment}</code></p></li><li><p><code>${apiLink}</code></p></li><li><p><code>${dashboardLink}</code></p></li><li><p><code>${api}</code></p></li><li><p><code>${policy}</code></p></li></ul></div></div></td></tr><tr><td><p><strong>Average Response Time</strong></p></td></tr><tr><td><p><strong>Response Codes</strong></p></td></tr><tr><td><p><strong>Policy Violations</strong></p></td></tr></tbody></table>

<table id="alert-variables"><caption>Table 2. Variable Definitions</caption> <colgroup><col> <col></colgroup><thead><tr><th>Variable</th><th>Definition</th></tr></thead><tbody><tr><td><p><code>${apiLink}</code></p></td><td><p>URL of the triggered API</p></td></tr><tr><td><p><code>${alertState}</code></p></td><td><p>State of the alert when it was triggered.</p><p>Available values are <code>OK</code> or <code>Alerting</code>.</p></td></tr><tr><td><p><code>${comparison}</code></p></td><td><p>* Above, above or equal, equal, below or equal, below</p></td></tr><tr><td><p><code>${condition}</code></p></td><td><p>Metric for which the alert is triggered</p></td></tr><tr><td><p><code>${environment}</code></p></td><td><p>Name of the environment in which the resource is deployed</p></td></tr><tr><td><p><code>${operator}</code></p></td><td><p>An operator, such as <code>&lt; &gt; =</code></p></td></tr><tr><td><p><code>${organization}</code></p></td><td><p>Name of the organization that owns the alert</p></td></tr><tr><td><p><code>${period}</code></p></td><td><p>Period of time over which to measure</p></td></tr><tr><td><p><code>${severity}</code></p></td><td><p>Severity of the alert</p></td></tr><tr><td><p><code>${threshold}</code></p></td><td><p>Count over the period of time that triggers the alert</p></td></tr><tr><td><p><code>${value}</code></p></td><td><p>Value of the metric that triggers the alert</p></td></tr></tbody></table>

## Pause and Edit API Alerts

Pausing an alert causes the alert to transition to **Paused**.

You can also edit an existing alert by following these steps:

1.  In API Manager, click **API Instances** in the left navigation bar.

2.  Click the API instance and version that you want to edit and then click **Alerts**.

3.  Click **Edit** from the three-dots menu (![5%](/mulesoft/current/en-us/gateway/1.12/_images/three-dots-menu.png)) on the alert you
    want to edit.

    ![A table that shows the name of the alert, the metrics it is based on, the severity, the state, and whether the alert is enabled](/mulesoft/current/en-us/gateway/1.12/_images/flex-alerts-edit.png)

## View and Delete Alerts

To view and delete alerts:

1.  From API Manager, click **API instances**

2.  Click the API instance whose alert you want to delete.

3.  Select **Alerts**.

    ![A table of API service contract alerts with an expanded alert named 'Test fail alert'](/mulesoft/current/en-us/gateway/1.12/_images/view-add-alert.png)

4.  Expand an alert in the list.

    Details about the alert options appear.

5.  Click **Delete** from the three-dots menu
    (![Three dots aligned vertically as a menu](/mulesoft/current/en-us/gateway/1.12/_images/three-dots-menu.png)) on the alert you want
    to delete. You can also delete an alert when editing it.

<!-- document id=c98e483f9e0142da584901c4a9a59628507a554bac9f2023fd8e03ac437a90e8 url=/mulesoft/current/en-us/gateway/1.9/flex-use-api-alerts.md -->

---
product: Omni Gateway
version: 1.9
---

# Using Flex Gateway API Alerts

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using API alerts, you can add and configure email notifications that flag unusual API behavior, such
as:

- An API response time over 60 seconds

- More than 1000 API requests in 30 seconds

See [Add API Alerts](#add-api-alerts) below.

## Types of API Alerts

Add any of the following alerts to notify you of the condition described:

- Total Request Count: Users request access to the API more times than allowed during a specified
  time. Specify time interval values from 1 through 999999999. To prevent data bursts, intervals are
  implemented as sliding windows instead of as absolute minute boundaries.

- Average Response Time: The response time of the API exceeds a specified timeout period.

- Response Codes: Upon receiving a request, the API returns an HTTP code of 400, 401, 403, 404, 408,
  500, 502, or 503 or a custom three-digit response.

- Policy Violation: An infraction of a specified policy governing the API occurs.

## How API Alerts Work

API alerts are triggered only when:

- The API state changes

  Note that the first occurrence of a state change might go undetected if a newly created alert does
  not include defined states.

- The alert conditions are met for the specified period of time

  For example, if an alert is configured to trigger when an API returns an HTTP code of 500 five or
  more times within a 10-minute period, it does not trigger if the API returns a code of 500 only
  once within that 10-minute period.

When configuring an API alert, you can select business group users and users outside your
organization to receive email notifications about the alert. Notifications include information about
events that trigger alerts as specified by severity level.

> [!NOTE] API Alerts are sent from `no-reply@mulesoft.com`. This cannot be customized.

- The first email describes the alert:

  `Your API, CesarDemoAPI - Basic:151 (Environment: "NewOne"), has received greater than 2 requests within 1 consecutive periods of 1 minutes.`

- Another email notifies you when the alert is resolved:

  `Your API Version, jsonplaceholderapi - 1.0.development, is no longer in an alert state. The number of policy violations was not greater than 1 in the last 1 consecutive periods of 1 minutes.`

After the first set of two notification emails is sent, API Manager stops listening for alerts until
the next alert period begins. This technique prevents repeated notification emails.

## Before You Begin

To view and delete alerts, ensure that you have:

- **Manage Alerts** permission to view and delete API alerts.

- **View Alerts** permission for view-only access to alerts.

## Add API Alerts

To track and manage APIs, you can add one or more API alerts to your API instances. Add different
[types of alerts](#types-of-api-alerts) based on your requirements.

The following table explains the number of active alerts per API instance:

<table><colgroup><col> <col></colgroup><thead><tr><th>Pricing Package</th><th>Active Alerts</th></tr></thead><tbody><tr><td><p>Anypoint Integration Starter</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Anypoint Integration Advanced</p></td><td><p>Up to 10</p></td></tr><tr><td><p>Gold Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Platinum Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Titanium Subscription</p></td><td><p>Up to 10</p></td></tr></tbody></table>

All subscriptions enable you to have as many non-active alerts as needed.

Pausing or deleting an active alert enables you to create new alerts if you have reached the maximum
number of active alerts.

Alerts are enabled by default when created. This setting cannot be modified.

> [!NOTE] Alerts cannot be added to API instances protected by
> [automated policies](https://docs.mulesoft.com/gateway/latest/policies-automated-overview).

To add an API alert:

1.  Navigate to **API Manager** > **API Administration** and click the API instance for which you
    want to add an alert.

2.  From the left navigation pane, select **Alerts** > **New alert**.

3.  Specify values for the displayed alert options:

    - **Name**:

      Type an alert name, for example, `trial-alert`. You can delete an alert anytime if not
      required.

    - **Severity**:

      Select a severity for the alert:

      - **Info**

        Assign to alerts that do not require immediate attention when triggered. This severity
        indicates that the metric should be passively monitored.

      - **Warning**

        Assign to alerts that require prompt attention when triggered. This severity indicates an
        alert should be closely monitored.

      - **Critical**

        Assign to alerts that require immediate attention when triggered. This severity indicates an
        alert should receive an immediate response.

4.  Specify the alert conditions:

    - **Metric**

      Condition that triggers the alert.

    - **Logic**

      When the alert is triggered, based on the occurrence rate defined in the **When number of
      occurrences are** and **For at least \[number of\] minutes** fields. You can select a maximum
      of ten response codes for alert conditions.

5.  Configure the email notification:

    - **Subject**

      Subject of the alert email to send when the alert is triggered. The subject can include
      variables. See [Variable Definitions](#alert-variables).

    - **Message**

      Body text for the email to send when the alert is triggered. The message body can include
      variables. See [Variable Definitions](#alert-variables).

    - **Recipients**

      Recipients of the alert email. You can select up to 20 platform user IDs and enter up to 20
      email addresses.

6.  Click **Create**.

Alerts appear as **Pending** when they are created. After the API receives traffic, the alert
changes to a state of **OK**. Depending on the value, the alert transitions to **OK** or
**Alerting**.

### Alert Email Template

You can use the following variables in the **Subject** and **Message** fields for basic email
alerts.

For the description of each variable, see [Variable Definitions](#alert-variables).

<table><caption>Table 1. Variables for Alerts</caption> <colgroup><col> <col></colgroup><thead><tr><th>Alert</th><th>Applicable Variables</th></tr></thead><tbody><tr><td><p><strong>Total Request Count</strong></p></td><td rowspan="4"><div><div><ul><li><p><code>${severity}</code></p></li><li><p><code>${operator}</code></p></li><li><p><code>${threshold}</code></p></li><li><p><code>${period}</code></p></li><li><p><code>${value}</code></p></li><li><p><code>${condition}</code></p></li><li><p><code>${organization}</code></p></li><li><p><code>${environment}</code></p></li><li><p><code>${apiLink}</code></p></li><li><p><code>${dashboardLink}</code></p></li><li><p><code>${api}</code></p></li><li><p><code>${policy}</code></p></li></ul></div></div></td></tr><tr><td><p><strong>Average Response Time</strong></p></td></tr><tr><td><p><strong>Response Codes</strong></p></td></tr><tr><td><p><strong>Policy Violations</strong></p></td></tr></tbody></table>

<table id="alert-variables"><caption>Table 2. Variable Definitions</caption> <colgroup><col> <col></colgroup><thead><tr><th>Variable</th><th>Definition</th></tr></thead><tbody><tr><td><p><code>${apiLink}</code></p></td><td><p>URL of the triggered API</p></td></tr><tr><td><p><code>${alertState}</code></p></td><td><p>State of the alert when it was triggered.</p><p>Available values are <code>OK</code> or <code>Alerting</code>.</p></td></tr><tr><td><p><code>${comparison}</code></p></td><td><p>* Above, above or equal, equal, below or equal, below</p></td></tr><tr><td><p><code>${condition}</code></p></td><td><p>Metric for which the alert is triggered</p></td></tr><tr><td><p><code>${environment}</code></p></td><td><p>Name of the environment in which the resource is deployed</p></td></tr><tr><td><p><code>${operator}</code></p></td><td><p>An operator, such as <code>&lt; &gt; =</code></p></td></tr><tr><td><p><code>${organization}</code></p></td><td><p>Name of the organization that owns the alert</p></td></tr><tr><td><p><code>${period}</code></p></td><td><p>Period of time over which to measure</p></td></tr><tr><td><p><code>${severity}</code></p></td><td><p>Severity of the alert</p></td></tr><tr><td><p><code>${threshold}</code></p></td><td><p>Count over the period of time that triggers the alert</p></td></tr><tr><td><p><code>${value}</code></p></td><td><p>Value of the metric that triggers the alert</p></td></tr></tbody></table>

## Pause and Edit API Alerts

Pausing an alert causes the alert to transition to **Paused**.

You can also edit an existing alert by following these steps:

1.  In API Manager, click **API Administration** in the left navigation bar.

2.  Click the API instance and version that you want to edit and then click **Alerts**.

3.  Click **Edit** from the three-dots menu (![5%](/mulesoft/current/en-us/gateway/1.9/_images/three-dots-menu.png)) on the alert you
    want to edit.

    ![A table that shows the name of the alert, the metrics it is based on, the severity, the state, and whether the alert is enabled](/mulesoft/current/en-us/gateway/1.9/_images/flex-alerts-edit.png)

## View and Delete Alerts

To view and delete alerts:

1.  From API Manager, click **API Administration > API instance**, and select **Alerts**.

    ![A table of API service contract alerts with an expanded alert named 'Test fail alert'](/mulesoft/current/en-us/gateway/1.9/_images/view-add-alert.png)

2.  Expand an alert in the list.

    Details about the alert options appear.

3.  Click **Delete** from the three-dots menu
    (![Three dots aligned vertically as a menu](/mulesoft/current/en-us/gateway/1.9/_images/three-dots-menu.png)) on the alert you want
    to delete. You can also delete an alert when editing it.

<!-- document id=a4a28cadf690ae18f5e496af50ed8bcf7797535e224e0cbd2299f694ded62db6 url=/mulesoft/current/en-us/gateway/1.13/use-api-alerts.md -->

---
product: Omni Gateway
version: 1.13
---

# Using Omni Gateway API Alerts

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using API alerts, you can add and configure email notifications that flag unusual API behavior, such
as:

- An API response time over 60 seconds

- More than 1000 API requests in 30 seconds

See [Add API Alerts](#add-api-alerts) below.

## Types of API Alerts

Add any of the following alerts to notify you of the condition described:

- Total Request Count: Users request access to the API more times than allowed during a specified
  time. Specify time interval values from 1 through 999999999. To prevent data bursts, intervals are
  implemented as sliding windows instead of as absolute minute boundaries.

- Average Response Time: The response time of the API exceeds a specified timeout period.

- Response Codes: Upon receiving a request, the API returns an HTTP code of 400, 401, 403, 404, 408,
  500, 502, or 503 or a custom three-digit response.

- Policy Violation: An infraction of a specified policy governing the API occurs.

## How API Alerts Work

API alerts are triggered only when:

- The API state changes

  Note that the first occurrence of a state change might go undetected if a newly created alert does
  not include defined states.

- The alert conditions are met for the specified period of time

  For example, if an alert is configured to trigger when an API returns an HTTP code of 500 five or
  more times within a 10-minute period, it does not trigger if the API returns a code of 500 only
  once within that 10-minute period.

When configuring an API alert, you can select business group users and users outside your
organization to receive email notifications about the alert. Notifications include information about
events that trigger alerts as specified by severity level.

> [!NOTE] API Alerts are sent from `no-reply@mulesoft.com`. This cannot be customized.

- The first email describes the alert:

  `Your API, CesarDemoAPI - Basic:151 (Environment: "NewOne"), has received greater than 2 requests within 1 consecutive periods of 1 minutes.`

- Another email notifies you when the alert is resolved:

  `Your API Version, jsonplaceholderapi - 1.0.development, is no longer in an alert state. The number of policy violations was not greater than 1 in the last 1 consecutive periods of 1 minutes.`

After the first set of two notification emails is sent, API Manager stops listening for alerts until
the next alert period begins. This technique prevents repeated notification emails.

## Before You Begin

To view and delete alerts, ensure that you have:

- **Manage Alerts** permission to view and delete API alerts.

- **View Alerts** permission for view-only access to alerts.

## Add API Alerts

To track and manage APIs, you can add one or more API alerts to your API instances. Add different
[types of alerts](#types-of-api-alerts) based on your requirements.

The following table explains the number of active alerts per API instance:

<table><colgroup><col> <col></colgroup><thead><tr><th>Pricing Package</th><th>Active Alerts</th></tr></thead><tbody><tr><td><p>Anypoint Integration Starter</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Anypoint Integration Advanced</p></td><td><p>Up to 10</p></td></tr><tr><td><p>Gold Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Platinum Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Titanium Subscription</p></td><td><p>Up to 10</p></td></tr></tbody></table>

All subscriptions enable you to have as many non-active alerts as needed.

Pausing or deleting an active alert enables you to create new alerts if you have reached the maximum
number of active alerts.

Alerts are enabled by default when created. This setting cannot be modified.

> [!NOTE] Alerts cannot be added to API instances protected by
> [automated policies](https://docs.mulesoft.com/gateway/latest/policies-automated-overview).

To add an API alert:

1.  Navigate to **API Manager** > **API Instances** and click the API instance for which you want to
    add an alert.

2.  From the left navigation pane, select **Alerts** > **New alert**.

3.  Specify values for the displayed alert options:

    - **Name**:

      Type an alert name, for example, `trial-alert`. You can delete an alert anytime if not
      required.

    - **Severity**:

      Select a severity for the alert:

      - **Info**

        Assign to alerts that do not require immediate attention when triggered. This severity
        indicates that the metric should be passively monitored.

      - **Warning**

        Assign to alerts that require prompt attention when triggered. This severity indicates an
        alert should be closely monitored.

      - **Critical**

        Assign to alerts that require immediate attention when triggered. This severity indicates an
        alert should receive an immediate response.

4.  Specify the alert conditions:

    - **Metric**

      Condition that triggers the alert.

    - **Logic**

      When the alert is triggered, based on the occurrence rate defined in the **When number of
      occurrences are** and **For at least \[number of\] minutes** fields. You can select a maximum
      of ten response codes for alert conditions.

5.  Configure the email notification:

    - **Subject**

      Subject of the alert email to send when the alert is triggered. The subject can include
      variables. See [Variable Definitions](#alert-variables).

    - **Message**

      Body text for the email to send when the alert is triggered. The message body can include
      variables. See [Variable Definitions](#alert-variables).

    - **Recipients**

      Recipients of the alert email. You can select up to 20 platform user IDs and enter up to 20
      email addresses.

6.  Click **Create**.

Alerts appear as **Pending** when they are created. After the API receives traffic, the alert
changes to a state of **OK**. Depending on the value, the alert transitions to **OK** or
**Alerting**.

### Alert Email Template

You can use the following variables in the **Subject** and **Message** fields for basic email
alerts.

For the description of each variable, see [Variable Definitions](#alert-variables).

<table><caption>Table 1. Variables for Alerts</caption> <colgroup><col> <col></colgroup><thead><tr><th>Alert</th><th>Applicable Variables</th></tr></thead><tbody><tr><td><p><strong>Total Request Count</strong></p></td><td rowspan="4"><div><div><ul><li><p><code>${severity}</code></p></li><li><p><code>${operator}</code></p></li><li><p><code>${threshold}</code></p></li><li><p><code>${period}</code></p></li><li><p><code>${value}</code></p></li><li><p><code>${condition}</code></p></li><li><p><code>${organization}</code></p></li><li><p><code>${environment}</code></p></li><li><p><code>${apiLink}</code></p></li><li><p><code>${dashboardLink}</code></p></li><li><p><code>${api}</code></p></li><li><p><code>${policy}</code></p></li></ul></div></div></td></tr><tr><td><p><strong>Average Response Time</strong></p></td></tr><tr><td><p><strong>Response Codes</strong></p></td></tr><tr><td><p><strong>Policy Violations</strong></p></td></tr></tbody></table>

<table id="alert-variables"><caption>Table 2. Variable Definitions</caption> <colgroup><col> <col></colgroup><thead><tr><th>Variable</th><th>Definition</th></tr></thead><tbody><tr><td><p><code>${apiLink}</code></p></td><td><p>URL of the triggered API</p></td></tr><tr><td><p><code>${alertState}</code></p></td><td><p>State of the alert when it was triggered.</p><p>Available values are <code>OK</code> or <code>Alerting</code>.</p></td></tr><tr><td><p><code>${comparison}</code></p></td><td><p>* Above, above or equal, equal, below or equal, below</p></td></tr><tr><td><p><code>${condition}</code></p></td><td><p>Metric for which the alert is triggered</p></td></tr><tr><td><p><code>${environment}</code></p></td><td><p>Name of the environment in which the resource is deployed</p></td></tr><tr><td><p><code>${operator}</code></p></td><td><p>An operator, such as <code>&lt; &gt; =</code></p></td></tr><tr><td><p><code>${organization}</code></p></td><td><p>Name of the organization that owns the alert</p></td></tr><tr><td><p><code>${period}</code></p></td><td><p>Period of time over which to measure</p></td></tr><tr><td><p><code>${severity}</code></p></td><td><p>Severity of the alert</p></td></tr><tr><td><p><code>${threshold}</code></p></td><td><p>Count over the period of time that triggers the alert</p></td></tr><tr><td><p><code>${value}</code></p></td><td><p>Value of the metric that triggers the alert</p></td></tr></tbody></table>

## Pause and Edit API Alerts

Pausing an alert causes the alert to transition to **Paused**.

You can also edit an existing alert by following these steps:

1.  In API Manager, click **API Instances** in the left navigation bar.

2.  Click the API instance and version that you want to edit and then click **Alerts**.

3.  Click **Edit** from the three-dots menu (![5%](/mulesoft/current/en-us/gateway/1.13/_images/three-dots-menu.png)) on the alert you
    want to edit.

    ![A table that shows the name of the alert, the metrics it is based on, the severity, the state, and whether the alert is enabled](/mulesoft/current/en-us/gateway/1.13/_images/alerts-edit.png)

## View and Delete Alerts

To view and delete alerts:

1.  From API Manager, click **API instances**

2.  Click the API instance whose alert you want to delete.

3.  Select **Alerts**.

    ![A table of API service contract alerts with an expanded alert named 'Test fail alert'](/mulesoft/current/en-us/gateway/1.13/_images/view-add-alert.png)

4.  Expand an alert in the list.

    Details about the alert options appear.

5.  Click **Delete** from the three-dots menu
    (![Three dots aligned vertically as a menu](/mulesoft/current/en-us/gateway/1.13/_images/three-dots-menu.png)) on the alert you want
    to delete. You can also delete an alert when editing it.

<!-- document id=f9cc21f15fc1b99d2e22fc0a79faff3727c5ba7495077f719ef18a25232e3e8a url=/mulesoft/current/en-us/gateway/latest/use-api-alerts.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Using Omni Gateway API Alerts

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Using API alerts, you can add and configure email notifications that flag unusual API behavior, such
as:

- An API response time over 60 seconds

- More than 1000 API requests in 30 seconds

See [Add API Alerts](#add-api-alerts) below.

## Types of API Alerts

Add any of the following alerts to notify you of the condition described:

- Total Request Count: Users request access to the API more times than allowed during a specified
  time. Specify time interval values from 1 through 999999999. To prevent data bursts, intervals are
  implemented as sliding windows instead of as absolute minute boundaries.

- Average Response Time: The response time of the API exceeds a specified timeout period.

- Response Codes: Upon receiving a request, the API returns an HTTP code of 400, 401, 403, 404, 408,
  500, 502, or 503 or a custom three-digit response.

- Policy Violation: An infraction of a specified policy governing the API occurs.

## How API Alerts Work

API alerts are triggered only when:

- The API state changes

  Note that the first occurrence of a state change might go undetected if a newly created alert does
  not include defined states.

- The alert conditions are met for the specified period of time

  For example, if an alert is configured to trigger when an API returns an HTTP code of 500 five or
  more times within a 10-minute period, it does not trigger if the API returns a code of 500 only
  once within that 10-minute period.

When configuring an API alert, you can select business group users and users outside your
organization to receive email notifications about the alert. Notifications include information about
events that trigger alerts as specified by severity level.

> [!NOTE] API Alerts are sent from `no-reply@mulesoft.com`. This cannot be customized.

- The first email describes the alert:

  `Your API, CesarDemoAPI - Basic:151 (Environment: "NewOne"), has received greater than 2 requests within 1 consecutive periods of 1 minutes.`

- Another email notifies you when the alert is resolved:

  `Your API Version, jsonplaceholderapi - 1.0.development, is no longer in an alert state. The number of policy violations was not greater than 1 in the last 1 consecutive periods of 1 minutes.`

After the first set of two notification emails is sent, API Manager stops listening for alerts until
the next alert period begins. This technique prevents repeated notification emails.

## Before You Begin

To view and delete alerts, ensure that you have:

- **Manage Alerts** permission to view and delete API alerts.

- **View Alerts** permission for view-only access to alerts.

## Add API Alerts

To track and manage APIs, you can add one or more API alerts to your API instances. Add different
[types of alerts](#types-of-api-alerts) based on your requirements.

The following table explains the number of active alerts per API instance:

<table><colgroup><col> <col></colgroup><thead><tr><th>Pricing Package</th><th>Active Alerts</th></tr></thead><tbody><tr><td><p>Anypoint Integration Starter</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Anypoint Integration Advanced</p></td><td><p>Up to 10</p></td></tr><tr><td><p>Gold Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Platinum Subscription</p></td><td><p>Up to 6</p></td></tr><tr><td><p>Titanium Subscription</p></td><td><p>Up to 10</p></td></tr></tbody></table>

All subscriptions enable you to have as many non-active alerts as needed.

Pausing or deleting an active alert enables you to create new alerts if you have reached the maximum
number of active alerts.

Alerts are enabled by default when created. This setting cannot be modified.

> [!NOTE] Alerts cannot be added to API instances protected by
> [automated policies](https://docs.mulesoft.com/gateway/latest/policies-automated-overview).

To add an API alert:

1.  Navigate to **API Manager** > **API Instances** and click the API instance for which you want to
    add an alert.

2.  From the left navigation pane, select **Alerts** > **New alert**.

3.  Specify values for the displayed alert options:

    - **Name**:

      Type an alert name, for example, `trial-alert`. You can delete an alert anytime if not
      required.

    - **Severity**:

      Select a severity for the alert:

      - **Info**

        Assign to alerts that do not require immediate attention when triggered. This severity
        indicates that the metric should be passively monitored.

      - **Warning**

        Assign to alerts that require prompt attention when triggered. This severity indicates an
        alert should be closely monitored.

      - **Critical**

        Assign to alerts that require immediate attention when triggered. This severity indicates an
        alert should receive an immediate response.

4.  Specify the alert conditions:

    - **Metric**

      Condition that triggers the alert.

    - **Logic**

      When the alert is triggered, based on the occurrence rate defined in the **When number of
      occurrences are** and **For at least \[number of\] minutes** fields. You can select a maximum
      of ten response codes for alert conditions.

5.  Configure the email notification:

    - **Subject**

      Subject of the alert email to send when the alert is triggered. The subject can include
      variables. See [Variable Definitions](#alert-variables).

    - **Message**

      Body text for the email to send when the alert is triggered. The message body can include
      variables. See [Variable Definitions](#alert-variables).

    - **Recipients**

      Recipients of the alert email. You can select up to 20 platform user IDs and enter up to 20
      email addresses.

6.  Click **Create**.

Alerts appear as **Pending** when they are created. After the API receives traffic, the alert
changes to a state of **OK**. Depending on the value, the alert transitions to **OK** or
**Alerting**.

### Alert Email Template

You can use the following variables in the **Subject** and **Message** fields for basic email
alerts.

For the description of each variable, see [Variable Definitions](#alert-variables).

<table><caption>Table 1. Variables for Alerts</caption> <colgroup><col> <col></colgroup><thead><tr><th>Alert</th><th>Applicable Variables</th></tr></thead><tbody><tr><td><p><strong>Total Request Count</strong></p></td><td rowspan="4"><div><div><ul><li><p><code>${severity}</code></p></li><li><p><code>${operator}</code></p></li><li><p><code>${threshold}</code></p></li><li><p><code>${period}</code></p></li><li><p><code>${value}</code></p></li><li><p><code>${condition}</code></p></li><li><p><code>${organization}</code></p></li><li><p><code>${environment}</code></p></li><li><p><code>${apiLink}</code></p></li><li><p><code>${dashboardLink}</code></p></li><li><p><code>${api}</code></p></li><li><p><code>${policy}</code></p></li></ul></div></div></td></tr><tr><td><p><strong>Average Response Time</strong></p></td></tr><tr><td><p><strong>Response Codes</strong></p></td></tr><tr><td><p><strong>Policy Violations</strong></p></td></tr></tbody></table>

<table id="alert-variables"><caption>Table 2. Variable Definitions</caption> <colgroup><col> <col></colgroup><thead><tr><th>Variable</th><th>Definition</th></tr></thead><tbody><tr><td><p><code>${apiLink}</code></p></td><td><p>URL of the triggered API</p></td></tr><tr><td><p><code>${alertState}</code></p></td><td><p>State of the alert when it was triggered.</p><p>Available values are <code>OK</code> or <code>Alerting</code>.</p></td></tr><tr><td><p><code>${comparison}</code></p></td><td><p>* Above, above or equal, equal, below or equal, below</p></td></tr><tr><td><p><code>${condition}</code></p></td><td><p>Metric for which the alert is triggered</p></td></tr><tr><td><p><code>${environment}</code></p></td><td><p>Name of the environment in which the resource is deployed</p></td></tr><tr><td><p><code>${operator}</code></p></td><td><p>An operator, such as <code>&lt; &gt; =</code></p></td></tr><tr><td><p><code>${organization}</code></p></td><td><p>Name of the organization that owns the alert</p></td></tr><tr><td><p><code>${period}</code></p></td><td><p>Period of time over which to measure</p></td></tr><tr><td><p><code>${severity}</code></p></td><td><p>Severity of the alert</p></td></tr><tr><td><p><code>${threshold}</code></p></td><td><p>Count over the period of time that triggers the alert</p></td></tr><tr><td><p><code>${value}</code></p></td><td><p>Value of the metric that triggers the alert</p></td></tr></tbody></table>

## Pause and Edit API Alerts

Pausing an alert causes the alert to transition to **Paused**.

You can also edit an existing alert by following these steps:

1.  In API Manager, click **API Instances** in the left navigation bar.

2.  Click the API instance and version that you want to edit and then click **Alerts**.

3.  Click **Edit** from the three-dots menu (![5%](/mulesoft/current/en-us/gateway/latest/_images/three-dots-menu.png)) on the alert you
    want to edit.

    ![A table that shows the name of the alert, the metrics it is based on, the severity, the state, and whether the alert is enabled](/mulesoft/current/en-us/gateway/latest/_images/alerts-edit.png)

## View and Delete Alerts

To view and delete alerts:

1.  From API Manager, click **API instances**

2.  Click the API instance whose alert you want to delete.

3.  Select **Alerts**.

    ![A table of API service contract alerts with an expanded alert named 'Test fail alert'](/mulesoft/current/en-us/gateway/latest/_images/view-add-alert.png)

4.  Expand an alert in the list.

    Details about the alert options appear.

5.  Click **Delete** from the three-dots menu
    (![Three dots aligned vertically as a menu](/mulesoft/current/en-us/gateway/latest/_images/three-dots-menu.png)) on the alert you want
    to delete. You can also delete an alert when editing it.

<!-- document id=0b405ca74475e138e0ef5f1004617b7490182f1d78e9e3a7718e529d056467d0 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-view-api-status.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing API Status in Runtime Manager for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Flex Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=04e665c858b69825cff0d56ef5efd00442eec73425b1af3c8eec646e2868a863 url=/mulesoft/current/en-us/gateway/1.9/flex-conn-view-api-status.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing API Status in Runtime Manager for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Flex Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=750ff95b82c39d17feb3d2b0e1fc07eeef06bf0e7c074c2f5707ef3cd74a49e7 url=/mulesoft/current/en-us/gateway/1.12/flex-managed-view-api-status.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing API Status in Runtime Manager for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Flex Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=cc952686abb7514e98c9626ac6909bf16e4e21799fe92a37fd0e04c1eb324a5b url=/mulesoft/current/en-us/gateway/1.9/flex-managed-view-api-status.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing API Status in Runtime Manager for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Flex Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=12b71ef7858d602105731e05ff8d63ef312cff08c4e5217defc092bb110efa39 url=/mulesoft/current/en-us/gateway/1.13/managed-view-api-status.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing API Status in Runtime Manager for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Omni Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=550e7260f512016076e2ff9c16a38ef4b7e2415151464ab9297b2c782d3039d2 url=/mulesoft/current/en-us/gateway/latest/managed-view-api-status.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing API Status in Runtime Manager for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Omni Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=f08cdd313977d7e092fa73bfb708a03421c2e66e5b50681e20230c5c5eb4250a url=/mulesoft/current/en-us/gateway/1.13/conn-view-api-status.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing API Status in Runtime Manager for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Omni Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=e694e07d643508545c4b8ab1d16a54e081d9bf34c0659c0852a9c0d157c4c008 url=/mulesoft/current/en-us/gateway/latest/conn-view-api-status.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing API Status in Runtime Manager for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To view basic information about APIs associated with Omni Gateway instances:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the gateway whose APIs you want to check.

4.  Click **APIs**.

    For each API, Runtime Manager shows the name, version, instance ID, label, and date on which it
    was added.

To see more detailed information and perform actions on your APIs, click **View details** to be
redirected to API Manager.

<!-- document id=83696332f6f86581d09b139ebe6efc582516fdbab8bb2d59c07c6a5f70855e08 url=/mulesoft/current/en-us/gateway/1.12/flex-conn-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing Key Metrics in API Manager for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Flex Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Flex Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Instances** page appears, showing a list of API instances that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Using Flex Gateway API Alerts](https://docs.mulesoft.com/gateway/1.12/flex-use-api-alerts)

- [Configuring Alerts in Anypoint Monitoring](https://docs.mulesoft.com/monitoring/alerts-hf).

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=71c5579c0aee11f609a6a159aedb68321a9e9471c33d84d430a731817e48dc9e url=/mulesoft/current/en-us/gateway/1.9/flex-conn-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Key Metrics in API Manager for Flex Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Flex Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Flex Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Administration** page appears, showing a list of APIs that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Using Flex Gateway API Alerts](https://docs.mulesoft.com/gateway/1.9/flex-use-api-alerts)

- [Configuring Alerts in Anypoint Monitoring](https://docs.mulesoft.com/monitoring/alerts-hf).

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=04ac2973ccd82ebae323bb61a1b4924d9c638a11e6e5954e37d4765aa923639c url=/mulesoft/current/en-us/gateway/1.12/flex-managed-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing Key Metrics in API Manager for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Flex Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Flex Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Instances** page appears, showing a list of API instances that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Monitoring Flex Gateway Metrics](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-status)

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=167bc3363d6eca4e04e524f9415778dfef3ffeac2f29932da1a7123b346477c5 url=/mulesoft/current/en-us/gateway/1.9/flex-managed-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Key Metrics in API Manager for Managed Flex Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Flex Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Flex Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Administration** page appears, showing a list of APIs that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Viewing Managed Flex Gateway Metrics](https://docs.mulesoft.com/gateway/1.9/flex-managed-view-status)

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=7e3edb5ee88375e8335de209c253bf7e4251b25d0c3ea83d4d659c6342d41326 url=/mulesoft/current/en-us/gateway/1.13/managed-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing Key Metrics in API Manager for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Omni Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Omni Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Instances** page appears, showing a list of API instances that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Monitoring Omni Gateway Metrics](https://docs.mulesoft.com/gateway/1.13/managed-view-status)

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=4d539c61072e331c1e66841ec6c05faead3fc587fa6ba548467f4dae7f42b97c url=/mulesoft/current/en-us/gateway/latest/managed-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing Key Metrics in API Manager for Managed Omni Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Omni Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Omni Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Instances** page appears, showing a list of API instances that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Monitoring Omni Gateway Metrics](https://docs.mulesoft.com/gateway/latest/managed-view-status)

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=bd0a0a9812f5abd19f346320df16bf9168059b1bd06e01b87912e9b62839678f url=/mulesoft/current/en-us/gateway/1.13/conn-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing Key Metrics in API Manager for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Omni Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Omni Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Instances** page appears, showing a list of API instances that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Using Omni Gateway API Alerts](https://docs.mulesoft.com/gateway/1.13/use-api-alerts)

- [Configuring Alerts in Anypoint Monitoring](https://docs.mulesoft.com/monitoring/alerts-hf).

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=8a8ae03c331ececf8efa8a8715b4f6be31fd8258391e526a62ae4ff56a1db8f1 url=/mulesoft/current/en-us/gateway/latest/conn-view-api-metrics.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing Key Metrics in API Manager for Omni Gateway in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

API Manager and Anypoint Monitoring collect metrics on active Omni Gateway API instances. You can
view charts related to these metrics and filter the data by date.

The metrics available in API Manager are considered **Key Metrics** and are described here. **Key
Metrics** are available with all Anypoint Platform subscriptions. For additional Omni Gateway API
metrics not included in the **Key Metrics** section, use
[Anypoint Monitoring](#monitoring::api-analytics-dashboard.adoc) (Anypoint Integration Advanced
package or Titanium subscriptions only). You can navigate to Anypoint Monitoring by clicking
**Anypoint Monitoring** from Anypoint Platform.

> [!NOTE] The **Mule API Analytics** tab in API Manager is currently not available for Omni Gateway
> APIs. Use the **Key Metrics** or the additional metrics in Anypoint Monitoring.

## Key Metrics

1.  Log in to Anypoint Platform.

2.  In the navigation bar or the Anypoint Platform page, click **API Manager**.  
    The **API Instances** page appears, showing a list of API instances that are available in your
    organization.

3.  Click the API instance.  
    The **API Summary** page appears, showing general information and the status of the API
    instance.

    To see an API instance in Anypoint Monitoring, from the **Key Metrics** section click **View
    more metrics in Anypoint Monitoring dashboard** or navigate to Anypoint Monitoring directly.

The **Key Metrics** section shows four charts. If charts do not appear for your API instance,
refresh your browser.

## Understanding Key Metrics

The **Key Metrics** section of the API summary contains the following charts:

Total Requests

Sum of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

Total Policy Violations

Sum of requests that return policy violations.

Data is aggregated in one minute increments.

Total Errors

Sum of HTTP response codes that occur in the selected time period. The response codes counted in
this metric are 400, 401, 402, 403, 404, 405, 408, 409, 410, 411, 412, 413, 415, 416, 417, 420, 422,
429, 500, 502, 503, 504, 504, 510, and 511.

Data is aggregated in one minute increments. In the chart, HTTP response codes are abbreviated as
4xx and 5xx.

Average Response Time

Average response time of requests in the selected time period for the given API.

Data is aggregated in one minute increments.

## Setting the Time Period for Key Metrics

You can view the data points collected for the last given period of time (such as the last 5 or 30
minutes) or over a given date and time range. Use the drop-down in the calendar icon to select the
time period to display.

## See Also

- [Using Omni Gateway API Alerts](https://docs.mulesoft.com/gateway/latest/use-api-alerts)

- [Configuring Alerts in Anypoint Monitoring](https://docs.mulesoft.com/monitoring/alerts-hf).

- [monitoring::api-analytics-dashboard.adoc](#monitoring::api-analytics-dashboard.adoc)

<!-- document id=9dd3f7d0927cb267b3f74befe16a0d3cfbb81ca0b2db0e0c16ec84bd75428f90 url=/mulesoft/current/en-us/gateway/1.9/flex-managed-view-status.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Managed Flex Gateway Metrics

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## View a Managed Flex Gateway Metrics in Runtime Manager

The Managed Flex Gateway Dashboard in Runtime Manager presents a comprehensive view of the gateway,
detailing its status, endpoints, private space, API capacity, request volume, data consumption, and
average CPU and memory usage. In addition, it provides metrics on latency and error count for
thorough monitoring.

To view information about a Managed Flex Gateway Instance:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the name of the Managed Flex Gateway to view its status.

<!-- document id=a1040a896ebe47a0ee4f27371940e4fec762c552d370c1d928ea5f964ca34257 url=/mulesoft/current/en-us/gateway/1.12/flex-managed-view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing Managed Flex Gateway Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Flex Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=aa2c65fa77929703b5eee4c311a5526b94aac1a2f66267cdfd9f12fb41097af0 url=/mulesoft/current/en-us/gateway/1.9/flex-managed-view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Managed Flex Gateway Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Flex Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=f8ed8e72bcab9641cc0670aa9c54121d6d6c7eb674c1222704249471e61ea5fd url=/mulesoft/current/en-us/gateway/1.13/managed-view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing Managed Omni Gateway Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Omni Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=a1a0c310ee5289b09632390b04d1f28f4468b7b63c03569cd62579b176565ecd url=/mulesoft/current/en-us/gateway/latest/managed-view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing Managed Omni Gateway Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Omni Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=21e93e2db7e20e1b122293c9bd416719c4d1d43966e86fa3c9dd7b33bbfb7d01 url=/mulesoft/current/en-us/gateway/1.12/flex-managed-view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing Runtime Logs in Runtime Manager for Flex Managed Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Flex Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Flex Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Flex Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Flex Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Managed Flex Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.12/flex-managed-view-logs-in-monitoring)

<!-- document id=b556bc4f9d7f012fb056cead08fcb9af9850efd40373d478aa01d9008292c29b url=/mulesoft/current/en-us/gateway/1.9/flex-managed-view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Runtime Logs in Runtime Manager for Flex Managed Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Flex Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Flex Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Flex Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Flex Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Managed Flex Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.9/flex-managed-view-logs-in-monitoring)

<!-- document id=1b7aacf58c96641d130edfdae5b8582f48c785fdcfa090e30dddd2831eb6ebff url=/mulesoft/current/en-us/gateway/1.13/managed-view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing Runtime Logs in Runtime Manager for Omni Managed Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Omni Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Omni Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Omni Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Omni Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Managed Omni Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.13/managed-view-logs-in-monitoring)

<!-- document id=87872d3abc6fd19aa8414d134d0db9655a85e365b57ed383a616920e6a75ad8b url=/mulesoft/current/en-us/gateway/latest/managed-view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing Runtime Logs in Runtime Manager for Omni Managed Gateway

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Omni Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Omni Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Omni Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Omni Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Managed Omni Gateway Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/latest/managed-view-logs-in-monitoring)

<!-- document id=98b4b0f2f5dc9380398b0e3a87032d2d907354be6e0dc9da92333aa42f853f29 url=/mulesoft/current/en-us/gateway/1.12/flex-view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing Runtime Logs in Runtime Manager in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Flex Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Flex Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Flex Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Flex Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.12/flex-view-logs-in-monitoring)

- [Configuring Flex Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.12/flex-conn-third-party-logs-config)

<!-- document id=3a2512deeb197f9ba7927db31ce902e0078402f9711022d893b181ab4543e633 url=/mulesoft/current/en-us/gateway/1.13/view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing Runtime Logs in Runtime Manager in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Omni Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Omni Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Omni Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Omni Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.13/view-logs-in-monitoring)

- [Configuring Omni Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.13/conn-third-party-logs-config)

<!-- document id=ce69c345e1e7802358980da1f25187a447cac9c78923cb6ca2694ea1347b71cc url=/mulesoft/current/en-us/gateway/1.9/flex-view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Runtime Logs in Runtime Manager in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Flex Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Flex Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Flex Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Flex Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/1.9/flex-view-logs-in-monitoring)

- [Configuring Flex Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/1.9/flex-conn-third-party-logs-config)

<!-- document id=4053b74d7945aaf58783e9a0aa61dee51b529b1ba80e2d7d71baae8bbb5e64bd url=/mulesoft/current/en-us/gateway/latest/view-logs-in-runtime-manager.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing Runtime Logs in Runtime Manager in Connected Mode

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Runtime Manager to view the runtime logs of your Omni Gateway. Runtime Manager enables you to
search for keywords within the logs and to filter by **Replica**, **Time Range**, and **Log Level**.

Runtime Manager stores up to 100 MB of logs per Omni Gateway for 30 days. Runtime Manager
automatically purges logs that go beyond 100 MB per Omni Gateway. If you need more storage, either
use Anypoint Monitoring to access these logs (Titanium subscription required) or use a third-party
logging service.

To access Omni Gateway runtime logs in Runtime Manager:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

## See Also

- [Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring](https://docs.mulesoft.com/gateway/latest/view-logs-in-monitoring)

- [Configuring Omni Gateway Log Output for Third-Party Services](https://docs.mulesoft.com/gateway/latest/conn-third-party-logs-config)

<!-- document id=7c0edb3c09bd40575ebb768a4114d71529807ae6d2e1969986fd148080e6c294 url=/mulesoft/current/en-us/gateway/1.12/flex-view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Flex Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=51a6b15d9e406143f617ce50d4735d2a85d5df6b077f06512b0a51d77744d62b url=/mulesoft/current/en-us/gateway/1.13/view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Omni Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=5e715abfc9eedde9662931710b495b32f56e851347cb2af9543fb59121441d2a url=/mulesoft/current/en-us/gateway/1.9/flex-view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Flex Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Click the name of the Flex Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=da0312959b8d8c473e42447d56b2a331a9619a79f49f3a54b8ca67b8833d74d0 url=/mulesoft/current/en-us/gateway/latest/view-logs-in-monitoring.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing Self-Managed Runtime and Access Logs in Anypoint Monitoring

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Use Anypoint Monitoring to see both runtime and access logs. Use the Anypoint Monitoring filtering
to see different detailed logging views.

To access Anypoint Monitoring from the Runtime Manager Omni Gateway UI:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Click the name of the Omni Gateway whose logs you want to view.

4.  Click **Logs**.

5.  Click **View logs in Anypoint Monitoring**.

    This action takes you to the Anypoint Monitoring UI.

<!-- document id=c9cd627e3af10d44500c59553fc709d8f50f24154a686236b6b7e2a8112f0e32 url=/mulesoft/current/en-us/gateway/1.12/flex-local-view-logs.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing Standard Output Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway maintains standard output logs for individual replicas. Use the standard output logs
for quick logging checks when additional logging output is not needed, such as ensuring when an
external service is running or API requests are reaching Flex Gateway.

You do not need to configure log output to view standard output logs. However, if you want access
logs to appear in standard output logs, you must apply a Message Logging policy to the APIs you want
to monitor. To apply a Message Logging policy, see
[Configuring Access logs](https://docs.mulesoft.com/gateway/1.12/flex-local-third-party-logs-config#configure-access-logs).

You can also configure additional Fluent Bit to enable custom logging outputs and customize the log
level info. To configure additional logging, see
[Configuring External Logs for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.12/flex-local-third-party-logs-config).

To view additional log outputs, find the appropriate method to view them. The following commands
display only the standard output logs.

## View Logs

To view the standard output logs of your replica, run one of the following commands:

For Linux:

```ssh
journalctl -u flex-gateway*
```

For Docker:

```ssh
docker logs -f <container-id>
```

For Kubernetes:

```ssh
kubectl logs -f <pod-name>
```

## See Also

- [Fluent Bit documentation](https://docs.fluentbit.io/manual)

<!-- document id=0e7a40ebd859ec4cce0ad1bf6a13f59eaa7176c36866b1ad8535beb5fe62cf40 url=/mulesoft/current/en-us/gateway/1.13/local-view-logs.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing Standard Output Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway maintains standard output logs for individual replicas. Use the standard output logs
for quick logging checks when additional logging output is not needed, such as ensuring when an
external service is running or API requests are reaching Omni Gateway.

You do not need to configure log output to view standard output logs. However, if you want access
logs to appear in standard output logs, you must apply a Message Logging policy to the APIs you want
to monitor. To apply a Message Logging policy, see
[Configuring Access logs](https://docs.mulesoft.com/gateway/1.13/local-third-party-logs-config#configure-access-logs).

You can also configure additional Fluent Bit to enable custom logging outputs and customize the log
level info. To configure additional logging, see
[Configuring External Logs for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-third-party-logs-config).

To view additional log outputs, find the appropriate method to view them. The following commands
display only the standard output logs.

## View Logs

To view the standard output logs of your replica, run one of the following commands:

For Linux:

```ssh
journalctl -u flex-gateway*
```

For Docker:

```ssh
docker logs -f <container-id>
```

For Kubernetes:

```ssh
kubectl logs -f <pod-name>
```

## See Also

- [Fluent Bit documentation](https://docs.fluentbit.io/manual)

<!-- document id=d1459086a81a5e61bc18558e57104ee90da7a08b68dfe22e14e8068d24763ec4 url=/mulesoft/current/en-us/gateway/1.9/flex-local-view-logs.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing Standard Output Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Flex Gateway maintains standard output logs for individual replicas. Use the standard output logs
for quick logging checks when additional logging output is not needed, such as ensuring when an
external service is running or API requests are reaching Flex Gateway.

You do not need to configure log output to view standard output logs. However, if you want access
logs to appear in standard output logs, you must apply a Message Logging policy to the APIs you want
to monitor. To apply a Message Logging policy, see
[Configuring Access logs](https://docs.mulesoft.com/gateway/1.9/flex-local-third-party-logs-config#configure-access-logs).

You can also configure additional Fluent Bit to enable custom logging outputs and customize the log
level info. To configure additional logging, see
[Configuring External Logs for Flex Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.9/flex-local-third-party-logs-config).

To view additional log outputs, find the appropriate method to view them. The following commands
display only the standard output logs.

## View Logs

To view the standard output logs of your replica, run one of the following commands:

For Linux:

```ssh
journalctl -u flex-gateway*
```

For Docker:

```ssh
docker logs -f <container-id>
```

For Kubernetes:

```ssh
kubectl logs -f <pod-name>
```

## See Also

- [Fluent Bit documentation](https://docs.fluentbit.io/manual)

<!-- document id=ae4f6560e38ef10bededdc508ad4ca970507ff26d4323a2ae154fc385adc30c6 url=/mulesoft/current/en-us/gateway/latest/local-view-logs.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing Standard Output Logs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Omni Gateway maintains standard output logs for individual replicas. Use the standard output logs
for quick logging checks when additional logging output is not needed, such as ensuring when an
external service is running or API requests are reaching Omni Gateway.

You do not need to configure log output to view standard output logs. However, if you want access
logs to appear in standard output logs, you must apply a Message Logging policy to the APIs you want
to monitor. To apply a Message Logging policy, see
[Configuring Access logs](https://docs.mulesoft.com/gateway/latest/local-third-party-logs-config#configure-access-logs).

You can also configure additional Fluent Bit to enable custom logging outputs and customize the log
level info. To configure additional logging, see
[Configuring External Logs for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/latest/local-third-party-logs-config).

To view additional log outputs, find the appropriate method to view them. The following commands
display only the standard output logs.

## View Logs

To view the standard output logs of your replica, run one of the following commands:

For Linux:

```ssh
journalctl -u flex-gateway*
```

For Docker:

```ssh
docker logs -f <container-id>
```

For Kubernetes:

```ssh
kubectl logs -f <pod-name>
```

## See Also

- [Fluent Bit documentation](https://docs.fluentbit.io/manual)

<!-- document id=a3978eb3343bf8799630c309d9be4ced339cfaa6eb0af13eeda4bfc2f51f9f17 url=/mulesoft/current/en-us/gateway/1.12/flex-view-replica-status.md -->

---
product: Omni Gateway
version: 1.12
---

# Viewing the Replica Status in Runtime Manager

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

In Runtime Manager, you can view the status of groups of Flex Replicas and individual Flex Replicas.

## Groups of Flex Replicas

To view information about the status of groups of Flex Replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.  
    By default, all Flex Gateways regardless of their status are shown. To filter by status, click
    the **Any Status** arrow and the status you want to filter.

The **Name** column lists the name and the number of connected replicas.

The **Status** column shows the connection status for the replicas associated with a particular
gateway.

The following table describes the meaning of each status for a group of replicas:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Group of Replicas</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>At least one replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>There are no replicas connected to the platform and no information on whether they are serving traffic.</p></div></div></td></tr></tbody></table>

## Individual Flex Replicas

To view information about the status of individual replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the name of the Flex Gateway whose individual replica statuses you want to view.

The **Status** column in the list of replicas shows the connection status for that particular
replica.

The following table describes the meaning of each status for a single replica:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Single Replica</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>The replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>The replica is not connected to the platform. There is no information on whether it is serving traffic. Disconnected replicas are deleted after seven days.</p></div></div></td></tr></tbody></table>

## See Also

- [View the API Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.12/flex-conn-view-api-status)

<!-- document id=13117fc30881d85236d1b66fed6b9d006ff7aa7bea1aa2d733cee986800fca38 url=/mulesoft/current/en-us/gateway/1.13/view-replica-status.md -->

---
product: Omni Gateway
version: 1.13
---

# Viewing the Replica Status in Runtime Manager

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

In Runtime Manager, you can view the status of groups of Omni Replicas and individual Omni Replicas.

## Groups of Omni Replicas

To view information about the status of groups of Omni Replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.  
    By default, all Omni Gateways regardless of their status are shown. To filter by status, click
    the **Any Status** arrow and the status you want to filter.

The **Name** column lists the name and the number of connected replicas.

The **Status** column shows the connection status for the replicas associated with a particular
gateway.

The following table describes the meaning of each status for a group of replicas:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Group of Replicas</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>At least one replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>There are no replicas connected to the platform and no information on whether they are serving traffic.</p></div></div></td></tr></tbody></table>

## Individual Omni Replicas

To view information about the status of individual replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the name of the Omni Gateway whose individual replica statuses you want to view.

The **Status** column in the list of replicas shows the connection status for that particular
replica.

The following table describes the meaning of each status for a single replica:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Single Replica</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>The replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>The replica is not connected to the platform. There is no information on whether it is serving traffic. Disconnected replicas are deleted after seven days.</p></div></div></td></tr></tbody></table>

## See Also

- [View the API Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.13/conn-view-api-status)

<!-- document id=295fe6514a364eb544b395c5a81963082c673f8cfe6162f1e6584ebfe1430453 url=/mulesoft/current/en-us/gateway/1.9/flex-view-replica-status.md -->

---
product: Omni Gateway
version: 1.9
---

# Viewing the Replica Status in Runtime Manager

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

In Runtime Manager, you can view the status of groups of Flex Replicas and individual Flex Replicas.

## Groups of Flex Replicas

To view information about the status of groups of Flex Replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.  
    By default, all Flex Gateways regardless of their status are shown. To filter by status, click
    the **Any Status** arrow and the status you want to filter.

The **Name** column lists the name and the number of connected replicas.

The **Status** column shows the connection status for the replicas associated with a particular
gateway.

The following table describes the meaning of each status for a group of replicas:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Group of Replicas</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>At least one replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>There are no replicas connected to the platform and no information on whether they are serving traffic.</p></div></div></td></tr></tbody></table>

## Individual Flex Replicas

To view information about the status of individual replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Flex Gateways** in the navigation menu.

3.  Select the name of the Flex Gateway whose individual replica statuses you want to view.

The **Status** column in the list of replicas shows the connection status for that particular
replica.

The following table describes the meaning of each status for a single replica:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Single Replica</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>The replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>The replica is not connected to the platform. There is no information on whether it is serving traffic. Disconnected replicas are deleted after seven days.</p></div></div></td></tr></tbody></table>

## See Also

- [View the API Status in Runtime Manager](https://docs.mulesoft.com/gateway/1.9/flex-conn-view-api-status)

<!-- document id=cc56fa1d2a73c71013a46aa92e2050d7e81bf838e85a613ae8714ee39b649259 url=/mulesoft/current/en-us/gateway/latest/view-replica-status.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Viewing the Replica Status in Runtime Manager

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

In Runtime Manager, you can view the status of groups of Omni Replicas and individual Omni Replicas.

## Groups of Omni Replicas

To view information about the status of groups of Omni Replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.  
    By default, all Omni Gateways regardless of their status are shown. To filter by status, click
    the **Any Status** arrow and the status you want to filter.

The **Name** column lists the name and the number of connected replicas.

The **Status** column shows the connection status for the replicas associated with a particular
gateway.

The following table describes the meaning of each status for a group of replicas:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Group of Replicas</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>At least one replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>There are no replicas connected to the platform and no information on whether they are serving traffic.</p></div></div></td></tr></tbody></table>

## Individual Omni Replicas

To view information about the status of individual replicas:

1.  From Anypoint Platform, select **Runtime Manager**.

2.  Select **Omni Gateways** in the navigation menu.

3.  Select the name of the Omni Gateway whose individual replica statuses you want to view.

The **Status** column in the list of replicas shows the connection status for that particular
replica.

The following table describes the meaning of each status for a single replica:

<table><colgroup><col> <col></colgroup><thead><tr><th>Status</th><th>Single Replica</th></tr></thead><tbody><tr><td><div><div><p>Running</p></div></div></td><td><div><div><p>The replica is connected to the platform and can serve traffic.</p></div></div></td></tr><tr><td><div><div><p>Not Running</p></div></div></td><td><div><div><p>The replica is not connected to the platform. There is no information on whether it is serving traffic. Disconnected replicas are deleted after seven days.</p></div></div></td></tr></tbody></table>

## See Also

- [View the API Status in Runtime Manager](https://docs.mulesoft.com/gateway/latest/conn-view-api-status)

<!-- document id=49cbc77562d7ccaf6a58eff5ce0202e3e5c2ca36a2144c94dd4bffd95077efee url=/mulesoft/current/en-us/gateway/1.13/policies-included-websocket-connection-limit.md -->

---
product: Omni Gateway
version: 1.13
keywords: websocket, connection limit, api gateway, flex gateway, gateway, policy
---

# WebSocket Connection Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>WebSocket Connection Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Limits the number of simultaneous WebSocket connections that each API instance allows</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/websocket-connection-limit-release-notes">WebSocket Connection Limit</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>429 - <code>Too many WebSocket connections</code></p></td></tr></tbody></table>

## Summary

The WebSocket Connection Limit policy tracks the number of active WebSocket connections for a
specific API instance. Omni Gateway identifies these requests by the `Upgrade: websocket` header and
ignores standard HTTP traffic. The WebSocket connection limit is distributed across Omni replicas.

When a WebSocket upgrade request arrives, Omni Gateway increments the counter to reserve capacity
before forwarding the handshake to the upstream service. If the upstream service doesn’t return a
`101 Switching Protocols` response, Omni Gateway releases the reservation. After a successful
WebSocket connection closes, Omni Gateway decrements the counter.

If the counter reaches the `maximumConnections` limit, Omni Gateway rejects the upgrade request with
a `429` error code.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: websocket-connection-limit-flex config: maximumConnections: <integer> //
REQUIRED, minimum 1

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumConnections</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p><code>100</code></p></div></div></td><td><div><div><p>Maximum number of simultaneous WebSocket connections allowed for the API instance. The value must be an integer of 1 or greater.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: websocket-connection-limit-flex
  config:
    maximumConnections: 500
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Maximum Connections</p></div></div></td><td><div><div><p>Maximum number of simultaneous WebSocket connections allowed for the API instance.</p></div></div></td><td><div><div><p><code>100</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/1.13/gateway-secure-apis)

<!-- document id=faed931e44303c084c98743e0c82cf2e1ef90efa9518352a602ec3e15eef6829 url=/mulesoft/current/en-us/gateway/latest/policies-included-websocket-connection-limit.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: websocket, connection limit, api gateway, flex gateway, gateway, policy
---

# WebSocket Connection Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>WebSocket Connection Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Limits the number of simultaneous WebSocket connections that each API instance allows</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/websocket-connection-limit-release-notes">WebSocket Connection Limit</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>429 - <code>Too many WebSocket connections</code></p></td></tr></tbody></table>

## Summary

The WebSocket Connection Limit policy tracks the number of active WebSocket connections for a
specific API instance. Omni Gateway identifies these requests by the `Upgrade: websocket` header and
ignores standard HTTP traffic. The WebSocket connection limit is distributed across Omni replicas.

When a WebSocket upgrade request arrives, Omni Gateway increments the counter to reserve capacity
before forwarding the handshake to the upstream service. If the upstream service doesn’t return a
`101 Switching Protocols` response, Omni Gateway releases the reservation. After a successful
WebSocket connection closes, Omni Gateway decrements the counter.

If the counter reaches the `maximumConnections` limit, Omni Gateway rejects the upgrade request with
a `429` error code.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: websocket-connection-limit-flex config: maximumConnections: <integer> //
REQUIRED, minimum 1

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumConnections</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p><code>100</code></p></div></div></td><td><div><div><p>Maximum number of simultaneous WebSocket connections allowed for the API instance. The value must be an integer of 1 or greater.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

```yaml
- policyRef:
    name: websocket-connection-limit-flex
  config:
    maximumConnections: 500
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Maximum Connections</p></div></div></td><td><div><div><p>Maximum number of simultaneous WebSocket connections allowed for the API instance.</p></div></div></td><td><div><div><p><code>100</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/latest/gateway-secure-apis)

<!-- document id=1079b7049dc9ac47ff96b0755ae649079ef9f2c8451db669d4a7101accb38f6f url=/mulesoft/current/en-us/gateway/latest/policies-included-web-services-security.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: web services security, ws-security, wss, usernametoken, xml signature, x.509, soap, wsdl, authentication, api gateway, flex gateway, gateway, policy
---

# WS-Security Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>WS-Security</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Validates Web Services Security (WS-Security) UsernameToken credentials, XML signatures, or both on inbound SOAP requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.14.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/web-services-security-release-notes">WS-Security Policy</a></p></td></tr><tr><td rowspan="3"><p><strong>Returned Status Codes</strong></p></td><td><p>400 - SOAP 1.2 sender fault: malformed request, unsupported or untrusted signature, or failed authentication</p></td></tr><tr><td><p>500 - SOAP 1.1 sender fault: malformed request, unsupported or untrusted signature, or failed authentication</p></td></tr><tr><td><p>500 - Server fault: API contracts aren’t available yet, so Omni Gateway can’t authenticate the UsernameToken</p></td></tr></tbody></table>

## Summary

> [!NOTE] The WS-Security Policy policy supports only WSDL (SOAP 1.1 and 1.2) APIs.

The Web Services Security (WS-Security) policy protects a SOAP service by validating the
`<wsse:Security>` header of each inbound request. You can enable either or both of these controls:

- **UsernameToken validation**: Authenticates the `<wsse:UsernameToken>` against the client
  applications that have contracts with the API. The username is the client ID, and the password is
  the client secret.

- **XML signature validation**: Verifies the `<ds:Signature>` in the Security header and confirms
  that the signing X.509 certificate chains to a certificate authority (CA) that you trust.

The WS-Security Policy policy is fail-closed. Every enabled control must succeed before Omni Gateway
forwards the request to the upstream service. Omni Gateway forwards the original headers and body
unchanged, and doesn’t modify responses. When a check fails, Omni Gateway returns a WS-Security SOAP
fault, and the request never reaches the upstream service.

The policy accepts plain SOAP requests with a `text/xml` or `application/soap+xml` content type, and
multipart SOAP requests with a `multipart/related` content type, such as MTOM/XOP and SOAP with
Attachments (SwA).

- To validate UsernameTokens, client applications must have a contract with the API. For more
  information, see
  [Approve or Reject Access Requests](https://docs.mulesoft.com/api-manager/latest/manage-client-apps-latest-task).

- To validate XML signatures, get the PEM-encoded certificates of the CAs that issue your client
  signing certificates.

## Configure WS-Security Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

Because UsernameToken validation requires API contracts that are only available for Managed Gateway
or Connected Mode, Local Mode only supports XML signature validation. To use the policy in local
mode, you must set `validateUsernameToken` to `false`.

\- policyRef: name: ws-security-policy-flex config: validateUsernameToken: <boolean> // REQUIRED,
set to false in Local Mode validateSignature: <boolean> // OPTIONAL, default: true trustAnchors:
<string> // REQUIRED when validateSignature is true

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>validateUsernameToken</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>Authenticates the UsernameToken username and <code>PasswordText</code> password against Anypoint Platform API contracts. Set to <code>false</code> in Local Mode, which doesn’t have API contracts.</p></div></div></td></tr><tr><td><div><div><p><code>validateSignature</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Verifies the XML signature, its X.509 certificate chain, and the required signed elements. Requires <code>trustAnchors</code>.</p></div></div></td></tr><tr><td><div><div><p><code>trustAnchors</code></p></div></div></td><td><div><div><p>Required when <code>validateSignature</code> is <code>true</code></p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>One to sixteen PEM-encoded X.509 CA certificates that the signing certificate must chain to. To specify more than one CA, concatenate the PEM blocks. Omni Gateway doesn’t use the operating system trust store.</p></div><div><p>Omni Gateway rejects a <code>trustAnchors</code> value that is empty, is malformed PEM, contains more than sixteen certificates, contains a certificate larger than 16 KiB, or has trailing data after a certificate.</p></div></div></td></tr></tbody></table>

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Validate UsernameToken</p></div></div></td><td><div><div><p>Authenticates the UsernameToken username and <code>PasswordText</code> password against Anypoint Platform API contracts. Enable either this field or <strong>Validate XML Signature</strong>.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Validate XML Signature</p></div></div></td><td><div><div><p>Verifies the XML signature, its X.509 certificate chain, and the required signed elements. Requires <strong>Trust Anchors (PEM)</strong>.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Trust Anchors (PEM)</p></div></div></td><td><div><div><p>One or more PEM-encoded X.509 CA certificates that the signing certificate must chain to.</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>Required when <strong>Validate XML Signature</strong> is enabled</p></div></div></td></tr></tbody></table>

### WS-Security Policy Configuration Examples

Examples that enable `validateUsernameToken` are only valid for Managed Gateway or Connected Mode.

This example enables both controls:

```yaml
- policyRef:
    name: ws-security-policy-flex
  config:
    validateUsernameToken: true
    validateSignature: true
    trustAnchors: |
      -----BEGIN CERTIFICATE-----
      MIID...issuing-or-root-CA...
      -----END CERTIFICATE-----
```

This example enables only UsernameToken validation. The policy doesn’t require, inspect, or trust an
XML signature:

```yaml
- policyRef:
    name: ws-security-policy-flex
  config:
    validateUsernameToken: true
    validateSignature: false
```

This example enables only XML Signature validation. The signature must cover the Timestamp. The
policy doesn’t require or authenticate a UsernameToken:

```yaml
- policyRef:
    name: ws-security-policy-flex
  config:
    validateUsernameToken: false
    validateSignature: true
    trustAnchors: |
      -----BEGIN CERTIFICATE-----
      MIID...issuing-or-root-CA...
      -----END CERTIFICATE-----
```

## How the WS-Security Policy Works

Omni Gateway applies these checks in order. The first check that fails determines the fault that
Omni Gateway returns:

1.  **Content type**: The request must use `text/xml`, `application/soap+xml`, or
    `multipart/related`. For a multipart request, Omni Gateway selects the root part, which is the
    part whose `Content-ID` matches the `start` parameter, or the first part when `start` is absent.
    The root part must use `7bit`, `8bit`, or `binary` `Content-Transfer-Encoding`, or omit the
    header. The policy validates only the SOAP envelope in the root part and forwards attachments to
    the upstream service without inspecting them.

2.  **SOAP envelope**: The envelope must be a single well-formed SOAP 1.1 or SOAP 1.2 document with
    no `<!DOCTYPE>` declaration.

3.  **Security header**: The SOAP `<Header>` must contain exactly one direct `<wsse:Security>`
    child. The policy ignores the SOAP 1.1 `actor` and SOAP 1.2 `role` attributes.

4.  **Required elements**: The Security header must contain exactly one of each element that the
    enabled controls require. The Security header must not contain XML Encryption elements.

5.  **Signature algorithms**: If XML Signature validation is enabled, the signature must use the
    supported algorithms, and its `KeyInfo` must reference an X.509 `<wsse:BinarySecurityToken>` in
    the same Security header.

6.  **Certificate trust**: If XML Signature validation is enabled, the signing certificate must
    chain to a configured trust anchor.

7.  **Signature verification**: If XML Signature validation is enabled, the signature and every
    reference digest must verify, and the signed references must cover the Timestamp. When
    UsernameToken validation is also enabled, the signed references must also cover the
    UsernameToken. The SOAP Body doesn’t need to be signed, but if the signature references the
    Body, Omni Gateway verifies it.

8.  **UsernameToken authentication**: If UsernameToken validation is enabled, the username and
    password must match the client ID and client secret of an API contract. Omni Gateway applies
    Unicode NFC normalization to the username before the lookup.

    The password must be `PasswordText`. If the `<wsse:Password>` element has no `Type` attribute,
    Omni Gateway treats the password as `PasswordText`. Omni Gateway always rejects
    `PasswordDigest`, because it can’t recompute the digest without the client secret in clear text.

### Supported Algorithms

The WS-Security Policy supports only these algorithms. It rejects a signature that uses any other
algorithm:

<table><colgroup><col> <col></colgroup><thead><tr><th>Purpose</th><th>Algorithm</th></tr></thead><tbody><tr><td><div><div><p>Signature</p></div></div></td><td><div><div><p>RSA-SHA256 (<code>http://www.w3.org/2001/04/xmldsig-more#rsa-sha256</code>)</p></div></div></td></tr><tr><td><div><div><p>Canonicalization</p></div></div></td><td><div><div><p>Exclusive XML Canonicalization without comments (<code>http://www.w3.org/2001/10/xml-exc-c14n#</code>)</p></div></div></td></tr><tr><td><div><div><p>Reference digest</p></div></div></td><td><div><div><p>SHA-256 (<code>http://www.w3.org/2001/04/xmlenc#sha256</code>)</p></div></div></td></tr></tbody></table>

The `<ds:KeyInfo>` element must reference the signing `<wsse:BinarySecurityToken>` by its `wsu:Id`.
The policy rejects other `KeyInfo` forms, `X509PKIPathv1` and `PKCS7` tokens, external references,
and attachment signature transforms.

### WS-Security Policy Certificate Requirements

The signing certificate must meet these requirements:

- It’s a base64-encoded DER X.509 v3 certificate of up to 16 KiB, with an RSA key of 2048 to 4096
  bits.

- It chains to a configured trust anchor through at most eight issuer certificates. The request can
  include intermediate CA certificates as additional `<wsse:BinarySecurityToken>` elements in the
  same Security header.

- Every certificate in the chain is valid at the time of the request, and every issuer is a CA
  certificate.

The policy doesn’t check certificate revocation or key usage.

### Principal Propagation

When UsernameToken validation is enabled and every enabled check succeeds, the WS-Security Policy
publishes the matched contract identity so that policies later in the chain can use it:

- `principal` and `client_id`: The client ID of the matched contract.

- `client_name`: The name of the client application.

- `sla-tier-id` and `sla-tier-name` properties: The SLA tier of the contract, when the contract has
  one.

The policy doesn’t publish the client secret or any certificate or signature data. Rejected requests
don’t change the authentication data.

When only XML Signature validation is enabled, the policy doesn’t publish an identity.

When both controls are enabled, a valid signature proves that a trusted signer protected the
UsernameToken, but it doesn’t bind the signing certificate to the client. Any certificate that
chains to a configured trust anchor can sign a UsernameToken for any client ID. The policy
authenticates the client ID and client secret separately against Anypoint API contracts.

## Request Example

This SOAP 1.1 request carries a signing certificate, a signed Timestamp, a UsernameToken, and a
signature that covers both the Timestamp and the UsernameToken:

```xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
               xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
               xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <soap:Header>
    <wsse:Security>
      <wsse:BinarySecurityToken wsu:Id="X509-signing-cert"
          ValueType="...#X509v3" EncodingType="...#Base64Binary">MIIB...leaf-cert...</wsse:BinarySecurityToken>
      <wsu:Timestamp wsu:Id="TS-1">
        <wsu:Created>2026-09-30T12:00:00Z</wsu:Created>
        <wsu:Expires>2026-09-30T12:05:00Z</wsu:Expires>
      </wsu:Timestamp>
      <wsse:UsernameToken wsu:Id="UT-1">
        <wsse:Username>contract-client-id</wsse:Username>
        <wsse:Password Type="...#PasswordText">contract-client-secret</wsse:Password>
      </wsse:UsernameToken>
      <ds:Signature><!-- RSA-SHA256 signature that references #TS-1 and #UT-1 --></ds:Signature>
    </wsse:Security>
  </soap:Header>
  <soap:Body><!-- application payload --></soap:Body>
</soap:Envelope>
```

With both controls enabled, Omni Gateway forwards this request when the certificate chains to a
configured trust anchor, the signature verifies over `TS-1` and `UT-1`, and the UsernameToken
matches an API contract.

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)

- [SOAP Schema Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-soap-schema-validation)

- [XML Threat Protection Policy](https://docs.mulesoft.com/gateway/latest/policies-included-xml-threat-protection)

- [Transport Layer Security Policy - Inbound](https://docs.mulesoft.com/gateway/latest/policies-included-tls)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/latest/gateway-secure-apis)

<!-- document id=0c76fb40bb3e99936c3cba1d0a0a8fa8291d50be6a92d4e118461c1e645f400d url=/mulesoft/current/en-us/gateway/1.12/policies-included-xml-threat-protection.md -->

---
product: Omni Gateway
version: 1.12
keywords: xml threat protection, api gateway, flex gateway, gateway, policy
---

# XML Threat Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>XML Threat Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Protects against malicious XML in API requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.10.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request</p></td></tr></tbody></table>

## Summary

Applications that process XML requests are susceptible to attacks characterized by unusual inflation
of elements, attributes, and deep nesting levels. Attackers use recursive techniques to consume
memory resources. Dramatic increases in the size of the application data often signal a security
risk. Use the XML Threat Protection policy to reject unusual requests that exceed the defined
expected size.

## Configuring Policy Parameters

### Flex Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: xml-threat-protection-flex config: maxNodeDepth: <number> // OPTIONAL, default:
-1 maxAttributeCountPerElement: <number> // OPTIONAL, default: -1 maxChildCount: <number> //
OPTIONAL, default: -1 maxTextLength: <number> // OPTIONAL, default: -1 maxAttributeLength: <number>
// OPTIONAL, default: -1 maxCommentLength: <number> // OPTIONAL, default: -1

> [!NOTE] Defining a parameter as `-1` means the parameter has no limit.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxNodeDepth</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum node depth of an XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAttributeCountPerElement</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of attributes in an element. Attributes used for defining namespaces are not counted.</p></div></div></td></tr><tr><td><div><div><p><code>maxChildCount</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of children of an element in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxTextLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of text nodes in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAttributeLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of an attribute in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxCommentLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of comment characters in the XML document.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: xml-threat-protection-flex config: maxNodeDepth: 1 maxAttributeCountPerElement:
1 maxChildCount: 2 maxTextLength: 20 maxAttributeLength: 20 maxCommentLength: 20

### Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Node Depth</p></div></div></td><td><div><div><p>Specifies the maximum node depth of an XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Attribute Count Per Element</p></div></div></td><td><div><div><p>Specifies the maximum number of attributes in an element. Attributes used for defining namespaces are not counted.</p></div></div></td></tr><tr><td><div><div><p>Maximum Child Count</p></div></div></td><td><div><div><p>Specifies the maximum number of children of an element in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Text Length</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of text nodes in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Attribute Length</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of an attribute in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Comment Length</p></div></div></td><td><div><div><p>Specifies the maximum number of comment characters in the XML document.</p></div></div></td></tr></tbody></table>

<!-- document id=a65a1b31c6758d233d9dfea2f6ce2f15fba56f128ff69b8b40b17254306b0bf4 url=/mulesoft/current/en-us/gateway/1.13/policies-included-xml-threat-protection.md -->

---
product: Omni Gateway
version: 1.13
keywords: xml threat protection, api gateway, flex gateway, gateway, policy
---

# XML Threat Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>XML Threat Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Protects against malicious XML in API requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.10.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/xml-threat-protection-release-notes">XML Threat Protection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request</p></td></tr></tbody></table>

## Summary

Applications that process XML requests are susceptible to attacks characterized by unusual inflation
of elements, attributes, and deep nesting levels. Attackers use recursive techniques to consume
memory resources. Dramatic increases in the size of the application data often signal a security
risk. Use the XML Threat Protection policy to reject unusual requests that exceed the defined
expected size.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: xml-threat-protection-flex config: maxNodeDepth: <number> // OPTIONAL, default:
-1 maxAttributeCountPerElement: <number> // OPTIONAL, default: -1 maxChildCount: <number> //
OPTIONAL, default: -1 maxTextLength: <number> // OPTIONAL, default: -1 maxAttributeLength: <number>
// OPTIONAL, default: -1 maxCommentLength: <number> // OPTIONAL, default: -1

> [!NOTE] Defining a parameter as `-1` means the parameter has no limit.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxNodeDepth</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum node depth of an XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAttributeCountPerElement</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of attributes in an element. Attributes used for defining namespaces are not counted.</p></div></div></td></tr><tr><td><div><div><p><code>maxChildCount</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of children of an element in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxTextLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of text nodes in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAttributeLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of an attribute in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxCommentLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of comment characters in the XML document.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: xml-threat-protection-flex config: maxNodeDepth: 1 maxAttributeCountPerElement:
1 maxChildCount: 2 maxTextLength: 20 maxAttributeLength: 20 maxCommentLength: 20

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Node Depth</p></div></div></td><td><div><div><p>Specifies the maximum node depth of an XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Attribute Count Per Element</p></div></div></td><td><div><div><p>Specifies the maximum number of attributes in an element. Attributes used for defining namespaces are not counted.</p></div></div></td></tr><tr><td><div><div><p>Maximum Child Count</p></div></div></td><td><div><div><p>Specifies the maximum number of children of an element in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Text Length</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of text nodes in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Attribute Length</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of an attribute in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Comment Length</p></div></div></td><td><div><div><p>Specifies the maximum number of comment characters in the XML document.</p></div></div></td></tr></tbody></table>

<!-- document id=cc6269cb840197b6ae1d99e5cdee4652dbd29edc47d84916dd3a13964da92d90 url=/mulesoft/current/en-us/gateway/latest/policies-included-xml-threat-protection.md -->

---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: xml threat protection, api gateway, flex gateway, gateway, policy
---

# XML Threat Protection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>XML Threat Protection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Protects against malicious XML in API requests</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.10.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/xml-threat-protection-release-notes">XML Threat Protection Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>400 - Bad Request</p></td></tr></tbody></table>

## Summary

Applications that process XML requests are susceptible to attacks characterized by unusual inflation
of elements, attributes, and deep nesting levels. Attackers use recursive techniques to consume
memory resources. Dramatic increases in the size of the application data often signal a security
risk. Use the XML Threat Protection policy to reject unusual requests that exceed the defined
expected size.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: xml-threat-protection-flex config: maxNodeDepth: <number> // OPTIONAL, default:
-1 maxAttributeCountPerElement: <number> // OPTIONAL, default: -1 maxChildCount: <number> //
OPTIONAL, default: -1 maxTextLength: <number> // OPTIONAL, default: -1 maxAttributeLength: <number>
// OPTIONAL, default: -1 maxCommentLength: <number> // OPTIONAL, default: -1

> [!NOTE] Defining a parameter as `-1` means the parameter has no limit.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maxNodeDepth</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum node depth of an XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAttributeCountPerElement</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of attributes in an element. Attributes used for defining namespaces are not counted.</p></div></div></td></tr><tr><td><div><div><p><code>maxChildCount</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of children of an element in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxTextLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of text nodes in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxAttributeLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of an attribute in the XML document.</p></div></div></td></tr><tr><td><div><div><p><code>maxCommentLength</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>-1</p></div></div></td><td><div><div><p>Specifies the maximum number of comment characters in the XML document.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: xml-threat-protection-flex config: maxNodeDepth: 1 maxAttributeCountPerElement:
1 maxChildCount: 2 maxTextLength: 20 maxAttributeLength: 20 maxCommentLength: 20

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col></colgroup><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Node Depth</p></div></div></td><td><div><div><p>Specifies the maximum node depth of an XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Attribute Count Per Element</p></div></div></td><td><div><div><p>Specifies the maximum number of attributes in an element. Attributes used for defining namespaces are not counted.</p></div></div></td></tr><tr><td><div><div><p>Maximum Child Count</p></div></div></td><td><div><div><p>Specifies the maximum number of children of an element in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Text Length</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of text nodes in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Attribute Length</p></div></div></td><td><div><div><p>Specifies the maximum length in characters of an attribute in the XML document.</p></div></div></td></tr><tr><td><div><div><p>Maximum Comment Length</p></div></div></td><td><div><div><p>Specifies the maximum number of comment characters in the XML document.</p></div></div></td></tr></tbody></table>