Skip to main content

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
Technical reference

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
info

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.

ParameterValue
Nameapi-whitelist
Applies toHTTP route api-route
Default ActionDeny

Rules:

ActionCIDRs
Allow10.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:

StateMeaning
ValidNotes are consistent and can be edited normally
AmbiguousNotes 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.
UnsupportedThe 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 0 to disable it.
ParameterValue
Namesecure-clients
Applies toGateway my-gateway
HTTP/2 Enabledtrue
HTTP/3 Enabledtrue

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)
ParameterValue
Nameresilient-backend
Applies toHTTP route api-route

Timeout Settings:

SettingValue
Request Timeout30s
Connect Timeout5s

Retry Settings:

SettingValue
Number of Retries3
Retry OnServer errors (5xx), Could not connect

Circuit Breaker:

SettingValue
Max Connections100
Max Pending Requests50

Creating a Policy​

Step-by-Step​

  1. Go to your gateway
  2. Click the Policies tab
  3. Click Create Policy
  4. Select the policy type
  5. Configure:
FieldDescriptionExample
NameUnique identifierapi-security
TypePolicy typeAccess control
Applies toThe gateway or route the rules coverHTTP route api-route
ConfigurationPolicy-specific settingsSee below
  1. 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 TypeCan apply to
Access controlGateway, HTTP route, gRPC route, TCP route
Connection settingsGateway only
Traffic & limitsGateway, HTTP route, gRPC route, TCP route, TLS route, UDP route

Apply to a gateway​

The rules cover all traffic through the gateway:

FieldValue
Applies toGateway
Namemy-gateway

Apply to a route​

The rules cover a single route:

FieldValue
Applies toHTTP route
Nameapi-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 filtering needs the real client IP

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:

ParameterValue
Nameinternal-only
Applies toHTTP route admin-route
Default ActionDeny

Rules:

ActionCIDRNote
Allow10.0.0.0/8Internal network
Allow172.16.0.0/12VPN range

IP Blocklist​

Block specific IP ranges:

ParameterValue
Nameblock-bad-actors
Applies toGateway my-gateway
Default ActionAllow

Rules:

ActionCIDRNote
Deny203.0.113.0/24Known bad range

CIDR Notation​

Common CIDR patterns:

CIDRDescription
10.0.0.0/8Private network (Class A)
172.16.0.0/12Private network (Class B)
192.168.0.0/16Private network (Class C)
0.0.0.0/0All IPv4 addresses
203.0.113.5/32Single IP address

Connection settings configuration​

HTTP/2 Settings​

Enable HTTP/2 for better performance:

ParameterValue
Namehttp2-enabled
Applies toGateway my-gateway
HTTP/2 Enabledtrue
Max Concurrent Streams100

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:

ParameterValue
Nametimeout-policy
Applies toHTTP route api-route

Timeout Settings:

SettingValueDescription
Request30sTotal request timeout
Connect5sConnection timeout
Idle60sIdle connection timeout

Retries​

Automatic retry on failures:

ParameterValue
Nameretry-policy
Applies toHTTP route api-route

Retry Settings:

SettingValue
Number of Retries3
Per Retry Timeout10s
Retry OnServer errors (5xx), Could not connect, Connection reset

Circuit Breaker​

Protect your app from overload:

ParameterValue
Namecircuit-breaker
Applies toHTTP route api-route

Circuit Breaker Settings:

SettingValue
Max Connections100
Max Pending Requests50
Max Requests1000

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.

SettingValue
Requests100
Time UnitSecond, 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.

SettingDescription
RequestsMaximum number of requests in the time window
Time UnitSecond, Minute, Hour, Day, Month, or Year
Client SelectorsOptional rules to match specific clients

Client selectors let you apply rate limits only to traffic matching certain criteria:

Selector TypeDescriptionExample
CIDRMatch requests by source IP range192.168.1.0/24
Header (Exact)Match requests with a specific header valueX-Tenant: acme
Header (Regex)Match requests where a header matches a regex patternUser-Agent: .*bot.*
Header (Distinct)Create a separate rate-limit counter for each unique header valueX-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.

tip

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.

  1. Go to the route detail page
  2. Find the policy in the Attached Policies section
  3. Click the detach icon
  4. Confirm the action
info

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.

info

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.

StateLabel in the interfaceMeaning
ActiveActiveThe policy is in effect on every target it applies to.
PartialPartly appliedThe policy is in effect on some targets but not all of them.
NotAppliedNot appliedThe policy is not in effect on any of its targets.
UnconfirmedNot confirmedSailOps has not confirmed whether this policy is in effect. This is normal for a freshly created policy.
NeedsAttentionNeeds attentionA 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:

HighlightShown when
Deny by default · N allow rules · M deny rulesAuthorization rules with an explicit default action
IP filteringAuthorization rules filtering by client CIDR
CORSCORS is configured
JWTJWT authentication is configured
Basic authHTTP Basic authentication is configured
N req/unitRate limiting with a specific limit (e.g. "100 req/minute")
Sticky (consistent hash)Consistent-hash load balancing
N retriesRetry count
Timeout XsRequest, 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.

WarningCodeMeaning
Not appliedPOLICY_CONFLICTEDAnother policy of the same kind already applies to this target. This policy is ignored.
OverriddenPOLICY_OVERRIDDENA policy applied directly to the route takes precedence, so this one has no effect.
Not acceptedPOLICY_NOT_ACCEPTEDSailOps could not apply this policy. Check its settings, or contact support.
Client IP not preservedCLIENT_IP_PRESERVATION_DISABLEDThe 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.

tip

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​

  1. Find the policy in the list
  2. Click the edit icon
  3. Modify the configuration
  4. Click Save
info

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.

info

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​

  1. Find the policy in the list
  2. Click the delete icon
  3. Confirm deletion
info

Policies labelled Managed by SailOps cannot be deleted. Change the setting that owns the policy instead.

warning

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:

ParameterValue
TypeAccess control
Nameadmin-whitelist
Applies toHTTP route admin-route
Default ActionDeny

Rules: Allow 10.0.0.0/8 (internal network only)

API Rate Protection​

Protect an API with a circuit breaker:

ParameterValue
TypeTraffic & limits
Nameapi-protection
Applies toHTTP 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:

ParameterValue
TypeTraffic & limits
Nameha-backend
Applies toHTTP route critical-api

Timeout Settings:

SettingValue
Request60s
Connect3s

Retry Settings:

SettingValue
Number of Retries3
Per Retry Timeout15s
Retry OnServer errors (5xx), Could not connect

Circuit Breaker: Max connections: 500

Troubleshooting​

Policy Not Applied​

  1. Check for policy warnings — another policy of the same kind may already cover the target
  2. Verify the policy applies to the gateway or route you expect
  3. Ensure that gateway or route still exists

IP Not Blocked/Allowed​

  1. Verify CIDR notation is correct
  2. Check what the policy applies to
  3. Review the default action setting

Timeouts Not Working​

  1. Verify the policy applies to the right route
  2. Check timeout values are reasonable
  3. Ensure your app is healthy