Policies
Control who reaches your services, how clients connect, and how requests reach your apps.
Overview
A policy applies a set of rules to a gateway or to one of its routes. SailOps offers three:
- Access control — IP filtering, CORS, JWT and HTTP Basic authentication: who may reach your services
- Connection settings — HTTP/2, HTTP/3 and client timeouts: how clients connect to the gateway (gateways only)
- Traffic & limits — load balancing, retries, timeouts, circuit breaking and rate limits: how requests reach your app
These are the names shown in the interface. On the API, and in the objects the platform stores, the original Envoy Gateway names are unchanged: access control is SecurityPolicy, connection settings is ClientTrafficPolicy, traffic & limits is BackendTrafficPolicy. Route kinds behave the same way — the interface shows "HTTP route", the API value stays HTTPRoute.
Policy Types
Access control
Control who can reach your services:
- Allow/Deny lists - Allow or block IP ranges using CIDR notation
- CIDR notes - Attach an optional note to each CIDR entry
- CORS - Configure cross-origin resource sharing
- JWT authentication - Validate JSON Web Tokens via a remote JWKS endpoint
- HTTP Basic authentication - Ask for a username and password before forwarding a request. You manage the list of users; passwords are stored hashed and are never shown again, so leave a user's password empty when editing to keep it
- Applies to - A gateway, one or more routes, or every target matching a set of labels
When an access control policy applies to a TCP route, only IP filtering is available. HTTP-specific features (CORS, JWT, basic auth) are not supported on TCP routes.
| Parameter | Value |
|---|---|
| Name | api-whitelist |
| Applies to | HTTP route api-route |
| Default Action | Deny |
Rules:
| Action | CIDRs |
|---|---|
| Allow | 10.0.0.0/8, 192.168.1.0/24 |
CIDR notes
Each CIDR entry in an authorization rule can carry an optional note (up to 100 characters). Notes are purely informational and help identify the purpose of an IP range (e.g., "Office", "VPN", "Partner API").
Notes are stored as metadata on the policy. When you edit a policy, SailOps preserves existing notes automatically. If that metadata becomes inconsistent (for example, after the policy was edited outside SailOps), the policy shows one of the following states:
| State | Meaning |
|---|---|
| Valid | Notes are consistent and can be edited normally |
| Ambiguous | Notes cannot be matched safely to their CIDR rules. Other edits (CORS, JWT, HTTP Basic authentication) are still allowed, but changing authorization rules requires explicitly reviewing and replacing the notes. |
| Unsupported | The note metadata uses an unknown or corrupted format. The policy cannot be edited through the interface. |
Connection settings
Configure how clients connect to your gateway. Connection settings apply to a gateway, never to an individual route.
- HTTP/2 settings - Stream window sizes and concurrent stream limits
- HTTP/3 - Enable QUIC protocol support
- Client timeout - Request received and idle timeouts. Set a timeout to
0to disable it.
| Parameter | Value |
|---|---|
| Name | secure-clients |
| Applies to | Gateway my-gateway |
| HTTP/2 Enabled | true |
| HTTP/3 Enabled | true |
Traffic & limits
Configure how requests reach your apps:
- Load balancing - Round robin, fewest active requests, random, or sticky (consistent hash)
- Timeouts - Request and connection timeouts
- Retries - Automatic retry configuration
- Circuit breaker - Protect your app from overload
- Rate limiting - Local or global request rate limits
- Applies to - A gateway, or one or more routes (HTTP, gRPC, TCP, TLS, UDP)
| Parameter | Value |
|---|---|
| Name | resilient-backend |
| Applies to | HTTP route api-route |
Timeout Settings:
| Setting | Value |
|---|---|
| Request Timeout | 30s |
| Connect Timeout | 5s |
Retry Settings:
| Setting | Value |
|---|---|
| Number of Retries | 3 |
| Retry On | Server errors (5xx), Could not connect |
Circuit Breaker:
| Setting | Value |
|---|---|
| Max Connections | 100 |
| Max Pending Requests | 50 |
Creating a Policy
Step-by-Step
- Go to your gateway
- Click the Policies tab
- Click Create Policy
- Select the policy type
- Configure:
| Field | Description | Example |
|---|---|---|
| Name | Unique identifier | api-security |
| Type | Policy type | Access control |
| Applies to | The gateway or route the rules cover | HTTP route api-route |
| Configuration | Policy-specific settings | See below |
- Click Create
Applies to
Every policy records what it applies to. A single policy can cover one or more gateways and routes.
Supported targets
| Policy Type | Can apply to |
|---|---|
| Access control | Gateway, HTTP route, gRPC route, TCP route |
| Connection settings | Gateway only |
| Traffic & limits | Gateway, HTTP route, gRPC route, TCP route, TLS route, UDP route |
Apply to a gateway
The rules cover all traffic through the gateway:
| Field | Value |
|---|---|
| Applies to | Gateway |
| Name | my-gateway |
Apply to a route
The rules cover a single route:
| Field | Value |
|---|---|
| Applies to | HTTP route |
| Name | api-route |
gRPC, TCP, TLS and UDP routes work the same way, depending on the policy type. On the API these are the Gateway, HTTPRoute, GRPCRoute, TCPRoute, TLSRoute and UDPRoute kinds.
A policy can also narrow its scope to a single part of its target — one listener of a gateway, or one rule of a route. The detail view says so under Applies to.
Some policies are applied automatically by SailOps rather than named target by target. Those are shown as Applied automatically by SailOps and cannot be detached from one route; the setting that owns them is what to change.
Managed by SailOps
Some policies are created and maintained by SailOps as the plumbing behind another setting — for example, the PROXY-protocol policy behind a gateway's client-IP configuration, or the access-control policy behind a database's public-access setting. These are labelled Managed by SailOps in the policy list and detail view.
Managed policies cannot be edited or deleted through the interface. To change the behaviour they enforce, update the setting that owns them (e.g., the gateway's client-IP option or the database's public-access toggle).
Access control configuration
IP rules only work when the gateway receives the visitor's real IP address. Gateways created by SailOps receive it by default; on an older gateway, enable its client IP setting before adding IP rules. SailOps refuses to save IP rules on a gateway that still sees the load balancer's address, because an allowlist would then block every caller and a blocklist would block none.
This setting identifies the client at the gateway. Your HTTP application must also trust the gateway to resolve X-Forwarded-For; otherwise its logs may still show the gateway's address. See Real Client IP for application configuration and the separate requirements for MQTT/TCP.
IP Allowlist
Only allow specific IP ranges:
| Parameter | Value |
|---|---|
| Name | internal-only |
| Applies to | HTTP route admin-route |
| Default Action | Deny |
Rules:
| Action | CIDR | Note |
|---|---|---|
| Allow | 10.0.0.0/8 | Internal network |
| Allow | 172.16.0.0/12 | VPN range |
IP Blocklist
Block specific IP ranges:
| Parameter | Value |
|---|---|
| Name | block-bad-actors |
| Applies to | Gateway my-gateway |
| Default Action | Allow |
Rules:
| Action | CIDR | Note |
|---|---|---|
| Deny | 203.0.113.0/24 | Known bad range |
CIDR Notation
Common CIDR patterns:
| CIDR | Description |
|---|---|
10.0.0.0/8 | Private network (Class A) |
172.16.0.0/12 | Private network (Class B) |
192.168.0.0/16 | Private network (Class C) |
0.0.0.0/0 | All IPv4 addresses |
203.0.113.5/32 | Single IP address |
Connection settings configuration
HTTP/2 Settings
Enable HTTP/2 for better performance:
| Parameter | Value |
|---|---|
| Name | http2-enabled |
| Applies to | Gateway my-gateway |
| HTTP/2 Enabled | true |
| Max Concurrent Streams | 100 |
HTTP/2 window sizes must be between 65,535 and 2,147,483,647 bytes.
HTTP/3 Settings
Enable QUIC protocol support by toggling HTTP/3 on. No additional parameters are needed — HTTP/3 is activated by the presence of the setting.
Traffic & limits configuration
Timeouts
Configure request timeouts:
| Parameter | Value |
|---|---|
| Name | timeout-policy |
| Applies to | HTTP route api-route |
Timeout Settings:
| Setting | Value | Description |
|---|---|---|
| Request | 30s | Total request timeout |
| Connect | 5s | Connection timeout |
| Idle | 60s | Idle connection timeout |
Retries
Automatic retry on failures:
| Parameter | Value |
|---|---|
| Name | retry-policy |
| Applies to | HTTP route api-route |
Retry Settings:
| Setting | Value |
|---|---|
| Number of Retries | 3 |
| Per Retry Timeout | 10s |
| Retry On | Server errors (5xx), Could not connect, Connection reset |
Circuit Breaker
Protect your app from overload:
| Parameter | Value |
|---|---|
| Name | circuit-breaker |
| Applies to | HTTP route api-route |
Circuit Breaker Settings:
| Setting | Value |
|---|---|
| Max Connections | 100 |
| Max Pending Requests | 50 |
| Max Requests | 1000 |
Rate Limiting
Control the rate of requests reaching your apps. Two modes are available:
Local Rate Limiting
Limits are applied per gateway instance independently. Simple to configure with no external dependencies.
| Setting | Value |
|---|---|
| Requests | 100 |
| Time Unit | Second, Minute, Hour, Day, Month, or Year |
You can add multiple rules. Each rule defines a maximum number of requests within a time window.
Example: Allow 100 requests per second per gateway instance.
Global Rate Limiting
Coordinated limits across all gateway instances. Useful when you need a fleet-wide rate cap regardless of how many replicas your gateway has.
| Setting | Description |
|---|---|
| Requests | Maximum number of requests in the time window |
| Time Unit | Second, Minute, Hour, Day, Month, or Year |
| Client Selectors | Optional rules to match specific clients |
Client selectors let you apply rate limits only to traffic matching certain criteria:
| Selector Type | Description | Example |
|---|---|---|
| CIDR | Match requests by source IP range | 192.168.1.0/24 |
| Header (Exact) | Match requests with a specific header value | X-Tenant: acme |
| Header (Regex) | Match requests where a header matches a regex pattern | User-Agent: .*bot.* |
| Header (Distinct) | Create a separate rate-limit counter for each unique header value | X-User-Id |
Both modes are shown the same way in the interface — as a number of requests per time unit, with the per-client rules underneath.
Start with Local rate limiting for simple use cases. Switch to Global when you need consistent rate enforcement across all gateway replicas.
Detaching a Policy from a Route
You can detach a policy from a route without deleting it. Detaching removes only that route from what the policy applies to — every other target is preserved. The policy itself is never deleted by a detach.
- Go to the route detail page
- Find the policy in the Attached Policies section
- Click the detach icon
- Confirm the action
Detaching a policy does not delete it. The policy remains in your gateway's policy list and can be reattached to any route. A policy that SailOps applies automatically cannot be detached from an individual route — change the setting that owns it instead.
Connection settings apply to a gateway as a whole, so they can never be attached to or detached from an individual route.
Policy status
Every policy shows a status that tells you whether it is in effect. The status is computed from what the platform reports and from whether the targets the policy names actually exist.
| State | Label in the interface | Meaning |
|---|---|---|
| Active | Active | The policy is in effect on every target it applies to. |
| Partial | Partly applied | The policy is in effect on some targets but not all of them. |
| NotApplied | Not applied | The policy is not in effect on any of its targets. |
| Unconfirmed | Not confirmed | SailOps has not confirmed whether this policy is in effect. This is normal for a freshly created policy. |
| NeedsAttention | Needs attention | A target the policy names does not exist in this project, or the platform reported an issue. |
The policy detail view shows, below the state badge:
- Summary — a plain-language sentence describing the situation
- Applied to — a per-target breakdown showing each gateway or route and its individual state
- Conditions — when something is wrong, a severity card with a description and a suggested action
The policy list also shows the status badge next to each policy name, along with highlight tags that summarize what each policy does. These tags are derived from the policy configuration and may include:
| Highlight | Shown when |
|---|---|
| Deny by default · N allow rules · M deny rules | Authorization rules with an explicit default action |
| IP filtering | Authorization rules filtering by client CIDR |
| CORS | CORS is configured |
| JWT | JWT authentication is configured |
| Basic auth | HTTP Basic authentication is configured |
| N req/unit | Rate limiting with a specific limit (e.g. "100 req/minute") |
| Sticky (consistent hash) | Consistent-hash load balancing |
| N retries | Retry count |
| Timeout Xs | Request, idle, or connect timeout value |
Warnings
A policy shows a warning when the platform could not apply it as expected. Only one policy of a given type can apply to a target — when several policies of the same type cover the same route or gateway, the oldest one wins and the others are flagged.
| Warning | Code | Meaning |
|---|---|---|
| Not applied | POLICY_CONFLICTED | Another policy of the same kind already applies to this target. This policy is ignored. |
| Overridden | POLICY_OVERRIDDEN | A policy applied directly to the route takes precedence, so this one has no effect. |
| Not accepted | POLICY_NOT_ACCEPTED | SailOps could not apply this policy. Check its settings, or contact support. |
| Client IP not preserved | CLIENT_IP_PRESERVATION_DISABLED | The policy filters by client IP, but the gateway does not receive the visitor's real IP yet, so the filter may match the load balancer instead of the real caller. |
Warnings appear on the policy list in the Policies tab, on the policy detail view, and on attached policies in the route detail view.
If you see a "Not applied" warning, check whether another policy of the same kind already covers the same route. Detach or delete the conflicting policy to resolve the issue.
Managing Policies
Filtering Policies
Use the filter buttons to view policies by type:
- All policies - Every policy on the gateway
- Access control - Access control policies only
- Connection settings - Connection settings only
- Traffic & limits - Traffic and limit policies only
Searching Policies
Search by:
- Policy name
- The name of the gateway or route it applies to
Viewing policy details
Click a policy to open its detail view. It shows, in this order:
- Status — the policy status badge, a summary sentence, the per-target breakdown, and any conditions with severity
- Applies to — the gateway and routes covered, in plain language
- The settings themselves — CORS, JWT, HTTP Basic authentication, authorization rules, rate limits, load balancing, health checks, circuit breaker, retries, timeouts, HTTP/2, HTTP/3
- Advanced settings — a collapsed list naming any setting the editor has no form for, such as OpenID Connect or external authorization, with a one-line summary of each
Editing a Policy
- Find the policy in the list
- Click the edit icon
- Modify the configuration
- Click Save
Only access control policies can be edited in the interface today. Connection settings and traffic & limits policies are created and deleted, not edited — replace one by deleting it and creating it again.
A policy the editor cannot represent losslessly is marked View only, and the reason is spelled out on the policy — for example that it applies to several targets, or that it uses a setting no form covers. This happens most often with policies created or modified outside SailOps. Delete and recreate such a policy to bring it back under the editor, or contact support.
Deleting a Policy
- Find the policy in the list
- Click the delete icon
- Confirm deletion
Policies labelled Managed by SailOps cannot be deleted. Change the setting that owns the policy instead.
Deleting a policy immediately removes the rules. Traffic will use default gateway behavior. If you only want to stop a policy from covering a specific route, use the detach action instead.
Common Use Cases
Secure Admin Panel
Restrict admin access to internal IPs:
| Parameter | Value |
|---|---|
| Type | Access control |
| Name | admin-whitelist |
| Applies to | HTTP route admin-route |
| Default Action | Deny |
Rules: Allow 10.0.0.0/8 (internal network only)
API Rate Protection
Protect an API with a circuit breaker:
| Parameter | Value |
|---|---|
| Type | Traffic & limits |
| Name | api-protection |
| Applies to | HTTP route api-route |
Circuit Breaker: Max connections: 200, Max pending requests: 100
Retry: 2 retries on 503 errors
High Availability Backend
Configure resilient connections to your app:
| Parameter | Value |
|---|---|
| Type | Traffic & limits |
| Name | ha-backend |
| Applies to | HTTP route critical-api |
Timeout Settings:
| Setting | Value |
|---|---|
| Request | 60s |
| Connect | 3s |
Retry Settings:
| Setting | Value |
|---|---|
| Number of Retries | 3 |
| Per Retry Timeout | 15s |
| Retry On | Server errors (5xx), Could not connect |
Circuit Breaker: Max connections: 500
Troubleshooting
Policy Not Applied
- Check for policy warnings — another policy of the same kind may already cover the target
- Verify the policy applies to the gateway or route you expect
- Ensure that gateway or route still exists
IP Not Blocked/Allowed
- Verify CIDR notation is correct
- Check what the policy applies to
- Review the default action setting
Timeouts Not Working
- Verify the policy applies to the right route
- Check timeout values are reasonable
- Ensure your app is healthy