Policies
Contrôlez qui accède à vos services, comment les clients se connectent et comment les requêtes atteignent vos applications.
Vue d'ensemble
Une policy applique un ensemble de règles à une gateway ou à l'une de ses routes. SailOps en propose trois :
- Access control — filtrage IP, CORS, authentification JWT et HTTP Basic : qui peut atteindre vos services
- Connection settings — HTTP/2, HTTP/3 et timeouts client : comment les clients se connectent à la gateway (gateways uniquement)
- Traffic & limits — load balancing, retries, timeouts, circuit breaker et rate limiting : comment les requêtes atteignent votre application
Ce sont les noms affichés dans l'interface. Sur l'API, et dans les objets stockés par la plateforme, les noms d'origine Envoy Gateway sont inchangés : Access control correspond à SecurityPolicy, Connection settings à ClientTrafficPolicy, Traffic & limits à BackendTrafficPolicy. Il en va de même pour les types de route : l'interface affiche « route HTTP », la valeur de l'API reste HTTPRoute.
Types de policies
Access control
Contrôlez l'accès à vos services :
- Listes Allow/Deny - Autorisez ou bloquez des plages d'IP en notation CIDR
- Notes CIDR - Associez une note optionnelle à chaque entrée CIDR
- CORS - Configurez le partage de ressources cross-origin
- Authentification JWT - Validez les JSON Web Tokens via un endpoint JWKS distant
- Authentification HTTP Basic - Demandez un identifiant et un mot de passe avant de transmettre une requête. Vous gérez la liste des utilisateurs ; les mots de passe sont stockés sous forme hachée et ne sont plus jamais affichés : laissez le mot de passe d'un utilisateur vide lors d'une modification pour le conserver
- S'applique à - Une gateway, une ou plusieurs routes, ou toutes les cibles correspondant à un ensemble de labels
Lorsqu'une policy access control cible une route TCP, seul le filtrage IP est disponible. Les fonctionnalités spécifiques HTTP (CORS, JWT, basic auth) ne sont pas supportées sur les routes TCP.
| Paramètre | Valeur |
|---|---|
| Nom | api-whitelist |
| S'applique à | Route HTTP api-route |
| Action par défaut | Deny |
Règles :
| Action | CIDRs |
|---|---|
| Allow | 10.0.0.0/8, 192.168.1.0/24 |
Notes CIDR
Chaque entrée CIDR dans une règle d'autorisation peut porter une note optionnelle (100 caractères maximum). Les notes sont purement informatives et permettent d'identifier la raison d'une plage d'IP (par exemple « Bureau », « VPN », « API partenaire »).
Les notes sont stockées sous forme de métadonnées sur la policy. Lorsque vous modifiez une policy, SailOps préserve automatiquement les notes existantes. Si les métadonnées deviennent incohérentes (par exemple après une modification en dehors de SailOps), la policy affiche l'un des états suivants :
| État | Signification |
|---|---|
| Valid | Les notes sont cohérentes et peuvent être modifiées normalement |
| Ambiguous | Les notes ne peuvent pas être associées de manière fiable à leurs règles CIDR. Les autres modifications (CORS, JWT, authentification HTTP Basic) restent possibles, mais modifier les règles d'autorisation nécessite de vérifier et remplacer explicitement les notes. |
| Unsupported | Les métadonnées de notes utilisent un format inconnu ou corrompu. La policy ne peut pas être modifiée via l'interface. |
Connection settings
Configurez comment les clients se connectent à votre gateway. Les connection settings s'appliquent à une gateway, jamais à une route individuelle.
- Paramètres HTTP/2 - Tailles de fenêtre de stream et limites de streams concurrents
- HTTP/3 - Activez le support du protocole QUIC
- Timeout client - Timeouts de réception de requête et d'inactivité. Définissez un timeout à
0pour le désactiver.
| Paramètre | Valeur |
|---|---|
| Nom | secure-clients |
| S'applique à | Gateway my-gateway |
| HTTP/2 activé | true |
| HTTP/3 activé | true |
Traffic & limits
Configurez comment les requêtes atteignent vos applications :
- Load balancing - Round robin, fewest active requests, random ou sticky (consistent hash)
- Timeouts - Timeouts de requête et de connexion
- Retries - Configuration de retry automatique
- Circuit breaker - Protégez votre application contre la surcharge
- Rate limiting - Limites de débit locales ou globales
- S'applique à - Une gateway, ou une ou plusieurs routes (HTTP, gRPC, TCP, TLS, UDP)
| Paramètre | Valeur |
|---|---|
| Nom | resilient-backend |
| S'applique à | Route HTTP api-route |
Paramètres de timeout :
| Paramètre | Valeur |
|---|---|
| Timeout de requête | 30s |
| Timeout de connexion | 5s |
Paramètres de retry :
| Paramètre | Valeur |
|---|---|
| Nombre de retries | 3 |
| Retry sur | Erreurs serveur (5xx), Connexion impossible |
Circuit Breaker :
| Paramètre | Valeur |
|---|---|
| Max connexions | 100 |
| Max requêtes en attente | 50 |
Créer une policy
Étape par étape
- Allez dans votre gateway
- Cliquez sur l'onglet Policies
- Cliquez sur Create Policy
- Sélectionnez le type de policy
- Configurez :
| Champ | Description | Exemple |
|---|---|---|
| Nom | Identifiant unique | api-security |
| Type | Type de policy | Access control |
| S'applique à | La gateway ou la route couverte par les règles | Route HTTP api-route |
| Configuration | Paramètres spécifiques à la policy | Voir ci-dessous |
- Cliquez sur Create
Cibles
Chaque policy enregistre ce à quoi elle s'applique. Une même policy peut couvrir une ou plusieurs gateways et routes.
Types de cible supportés
| Type de policy | Peut s'appliquer à |
|---|---|
| Access control | Gateway, route HTTP, route gRPC, route TCP |
| Connection settings | Gateway uniquement |
| Traffic & limits | Gateway, route HTTP, route gRPC, route TCP, route TLS, route UDP |
Appliquer à une gateway
Les règles couvrent tout le trafic passant par la gateway :
| Champ | Valeur |
|---|---|
| S'applique à | Gateway |
| Nom | my-gateway |
Appliquer à une route
Les règles couvrent une route spécifique :
| Champ | Valeur |
|---|---|
| S'applique à | Route HTTP |
| Nom | api-route |
Les routes gRPC, TCP, TLS et UDP fonctionnent de la même manière, selon le type de policy. Sur l'API, ce sont les kinds Gateway, HTTPRoute, GRPCRoute, TCPRoute, TLSRoute et UDPRoute.
Une policy peut aussi restreindre sa portée à une partie de sa cible — un listener d'une gateway, ou une règle d'une route. La vue de détail le précise sous S'applique à.
Certaines policies sont appliquées automatiquement par SailOps plutôt que nommées cible par cible. Celles-ci sont affichées comme Applied automatically by SailOps et ne peuvent pas être détachées d'une route individuelle ; c'est le paramètre qui les contrôle qu'il faut modifier.
Managed by SailOps
Certaines policies sont créées et maintenues par SailOps comme mécanisme interne d'un autre paramètre — par exemple, la policy PROXY-protocol derrière la configuration d'IP cliente d'une gateway, ou la policy access control derrière le paramètre d'accès public d'une base de données. Celles-ci portent le libellé Managed by SailOps dans la liste et la vue de détail des policies.
Les policies gérées par SailOps ne peuvent être ni modifiées ni supprimées via l'interface. Pour changer le comportement qu'elles appliquent, modifiez le paramètre qui les contrôle (par exemple, l'option d'IP cliente de la gateway ou le paramètre d'accès public de la base de données).
Configuration « Access control »
Les règles IP ne fonctionnent que si la gateway reçoit l'adresse IP réelle du visiteur. Les gateways créées par SailOps la reçoivent par défaut ; sur une gateway plus ancienne, activez son option d'IP cliente avant d'ajouter des règles IP. SailOps refuse d'enregistrer des règles IP sur une gateway qui ne voit encore que l'adresse du load balancer, car une liste blanche bloquerait alors tous les appelants et une liste noire n'en bloquerait aucun.
Ce réglage identifie le client côté gateway. Votre application HTTP doit aussi faire confiance à la gateway pour interpréter X-Forwarded-For ; sinon ses logs peuvent toujours afficher l'adresse de la gateway. Consultez IP réelle du client pour la configuration applicative et les prérequis distincts de MQTT/TCP.
Liste blanche d'IP
N'autoriser que des plages d'IP spécifiques :
| Paramètre | Valeur |
|---|---|
| Nom | internal-only |
| S'applique à | Route HTTP admin-route |
| Action par défaut | Deny |
Règles :
| Action | CIDR | Note |
|---|---|---|
| Allow | 10.0.0.0/8 | Réseau interne |
| Allow | 172.16.0.0/12 | Plage VPN |
Liste noire d'IP
Bloquer des plages d'IP spécifiques :
| Paramètre | Valeur |
|---|---|
| Nom | block-bad-actors |
| S'applique à | Gateway my-gateway |
| Action par défaut | Allow |
Règles :
| Action | CIDR | Note |
|---|---|---|
| Deny | 203.0.113.0/24 | Plage connue comme malveillante |
Notation CIDR
Patterns CIDR courants :
| CIDR | Description |
|---|---|
10.0.0.0/8 | Réseau privé (Classe A) |
172.16.0.0/12 | Réseau privé (Classe B) |
192.168.0.0/16 | Réseau privé (Classe C) |
0.0.0.0/0 | Toutes les adresses IPv4 |
203.0.113.5/32 | Une seule adresse IP |
Configuration « Connection settings »
Paramètres HTTP/2
Activer HTTP/2 pour de meilleures performances :
| Paramètre | Valeur |
|---|---|
| Nom | http2-enabled |
| S'applique à | Gateway my-gateway |
| HTTP/2 activé | true |
| Max streams concurrents | 100 |
Les tailles de fenêtre HTTP/2 doivent être comprises entre 65 535 et 2 147 483 647 octets.
Paramètres HTTP/3
Activez le support du protocole QUIC en activant HTTP/3. Aucun paramètre supplémentaire n'est nécessaire — HTTP/3 est activé par la présence du paramètre.
Configuration « Traffic & limits »
Timeouts
Configurer les timeouts de requête :
| Paramètre | Valeur |
|---|---|
| Nom | timeout-policy |
| S'applique à | Route HTTP api-route |
Paramètres de timeout :
| Paramètre | Valeur | Description |
|---|---|---|
| Request | 30s | Timeout total de requête |
| Connect | 5s | Timeout de connexion |
| Idle | 60s | Timeout de connexion inactive |
Retries
Retry automatique sur échecs :
| Paramètre | Valeur |
|---|---|
| Nom | retry-policy |
| S'applique à | Route HTTP api-route |
Paramètres de retry :
| Paramètre | Valeur |
|---|---|
| Nombre de retries | 3 |
| Timeout par retry | 10s |
| Retry sur | Erreurs serveur (5xx), Connexion impossible, Connexion réinitialisée |
Circuit Breaker
Protéger votre application contre la surcharge :
| Paramètre | Valeur |
|---|---|
| Nom | circuit-breaker |
| S'applique à | Route HTTP api-route |
Paramètres du Circuit Breaker :
| Paramètre | Valeur |
|---|---|
| Max connexions | 100 |
| Max requêtes en attente | 50 |
| Max requêtes | 1000 |
Rate Limiting
Contrôlez le débit de requêtes atteignant vos applications. Deux modes sont disponibles :
Rate Limiting Local
Les limites sont appliquées par instance de gateway indépendamment. Simple à configurer sans dépendance externe.
| Paramètre | Valeur |
|---|---|
| Requêtes | 100 |
| Unité de temps | Second, Minute, Hour, Day, Month ou Year |
Vous pouvez ajouter plusieurs règles. Chaque règle définit un nombre maximum de requêtes dans une fenêtre de temps.
Exemple : Autoriser 100 requêtes par seconde par instance de gateway.
Rate Limiting Global
Limites coordonnées entre toutes les instances de gateway. Utile quand vous avez besoin d'un plafond de débit global indépendamment du nombre de réplicas de votre gateway.
| Paramètre | Description |
|---|---|
| Requêtes | Nombre maximum de requêtes dans la fenêtre de temps |
| Unité de temps | Second, Minute, Hour, Day, Month ou Year |
| Client Selectors | Règles optionnelles pour cibler des clients spécifiques |
Les client selectors permettent d'appliquer les limites de débit uniquement au trafic correspondant à certains critères :
| Type de sélecteur | Description | Exemple |
|---|---|---|
| CIDR | Correspondance par plage d'IP source | 192.168.1.0/24 |
| Header (Exact) | Correspondance avec une valeur de header spécifique | X-Tenant: acme |
| Header (Regex) | Correspondance quand un header correspond à un pattern regex | User-Agent: .*bot.* |
| Header (Distinct) | Crée un compteur de rate-limit séparé pour chaque valeur unique du header | X-User-Id |
Les deux modes sont présentés de la même manière dans l'interface — un nombre de requêtes par unité de temps, avec les règles par client en dessous.
Commencez avec le rate limiting Local pour les cas simples. Passez au Global quand vous avez besoin d'un contrôle de débit cohérent entre tous les réplicas du gateway.
Détacher une policy d'une route
Vous pouvez détacher une policy d'une route sans la supprimer. Le détachement retire uniquement cette route de ce à quoi la policy s'applique — toutes les autres cibles sont conservées. La policy elle-même n'est jamais supprimée par un détachement.
- Allez sur la page de détail de la route
- Trouvez la policy dans la section Attached Policies
- Cliquez sur l'icône de détachement
- Confirmez l'action
Détacher une policy ne la supprime pas. La policy reste dans la liste des policies de votre gateway et peut être réattachée à n'importe quelle route. Une policy appliquée automatiquement par SailOps ne peut pas être détachée d'une route individuelle — modifiez le paramètre qui la contrôle à la place.
Les connection settings s'appliquent à une gateway dans son ensemble : elles ne peuvent donc jamais être attachées ou détachées d'une route individuelle.
Statut de policy
Chaque policy affiche un statut qui vous indique si elle est en vigueur. Le statut est calculé à partir de ce que la plateforme rapporte et de l'existence effective des cibles nommées par la policy.
| État | Libellé dans l'interface | Signification |
|---|---|---|
| Active | Active | La policy est en vigueur sur toutes les cibles auxquelles elle s'applique. |
| Partial | Partly applied | La policy est en vigueur sur certaines cibles mais pas toutes. |
| NotApplied | Not applied | La policy n'est en vigueur sur aucune de ses cibles. |
| Unconfirmed | Not confirmed | SailOps n'a pas confirmé si cette policy est en vigueur. C'est normal pour une policy fraîchement créée. |
| NeedsAttention | Needs attention | Une cible nommée par la policy n'existe pas dans ce projet, ou la plateforme a signalé un problème. |
La vue de détail d'une policy affiche, sous le badge d'état :
- Résumé — une phrase en langage courant décrivant la situation
- Applied to — un détail par cible montrant chaque gateway ou route et son état individuel
- Conditions — lorsqu'un problème est détecté, une carte avec la sévérité, une description et une action suggérée
La liste des policies affiche également le badge de statut à côté du nom de chaque policy, accompagné de tags résumant ce que fait chaque policy. Ces tags sont dérivés de la configuration de la policy et peuvent inclure :
| Tag | Affiché quand |
|---|---|
| Deny by default · N allow rules · M deny rules | Règles d'autorisation avec une action par défaut explicite |
| IP filtering | Règles d'autorisation filtrant par CIDR client |
| CORS | CORS est configuré |
| JWT | Authentification JWT est configurée |
| Basic auth | L'authentification HTTP Basic est configurée |
| N req/unit | Rate limiting avec une limite spécifique (par ex. « 100 req/minute ») |
| Sticky (consistent hash) | Load balancing en consistent hash |
| N retries | Nombre de retries |
| Timeout Xs | Valeur de timeout de requête, d'inactivité ou de connexion |
Avertissements
Une policy affiche un avertissement lorsque la plateforme n'a pas pu l'appliquer comme prévu. Une seule policy d'un type donné peut s'appliquer à une cible — lorsque plusieurs policies du même type couvrent la même route ou gateway, la plus ancienne est prioritaire et les autres sont signalées.
| Avertissement | Code | Signification |
|---|---|---|
| Not applied | POLICY_CONFLICTED | Une autre policy du même type s'applique déjà à cette cible. Celle-ci est ignorée. |
| Overridden | POLICY_OVERRIDDEN | Une policy appliquée directement à la route est prioritaire ; celle-ci n'a donc aucun effet. |
| Not accepted | POLICY_NOT_ACCEPTED | SailOps n'a pas pu appliquer cette policy. Vérifiez ses paramètres, ou contactez le support. |
| Client IP not preserved | CLIENT_IP_PRESERVATION_DISABLED | La policy filtre par adresse IP cliente, mais la gateway ne reçoit pas encore l'IP réelle du visiteur : le filtre risque de correspondre au load balancer plutôt qu'à l'appelant réel. |
Les avertissements apparaissent dans la liste des policies de l'onglet Policies, dans la vue de détail d'une policy, et sur les policies attachées dans la vue de détail d'une route.
Si vous voyez un avertissement « Not applied », vérifiez si une autre policy du même type cible déjà la même route. Détachez ou supprimez la policy en conflit pour résoudre le problème.
Gestion des policies
Filtrer les policies
Utilisez les boutons de filtre pour voir les policies par type :
- All policies — toutes les policies de la gateway
- Access control — contrôle d'accès uniquement
- Connection settings — paramètres de connexion uniquement
- Traffic & limits — trafic et limites uniquement
Rechercher des policies
Recherchez par :
- Nom de policy
- Nom de la gateway ou de la route à laquelle elle s'applique
Voir les détails d'une policy
Cliquez sur une policy pour ouvrir sa vue de détail. Elle affiche, dans cet ordre :
- Status — le badge de statut de policy, une phrase de résumé, le détail par cible, et les éventuelles conditions avec leur sévérité
- S'applique à — la gateway et les routes couvertes, en langage courant
- Les paramètres eux-mêmes — CORS, JWT, authentification HTTP Basic, règles d'autorisation, rate limits, load balancing, health checks, circuit breaker, retries, timeouts, HTTP/2, HTTP/3
- Advanced settings — une liste repliable nommant chaque paramètre pour lequel l'éditeur n'a pas de formulaire, comme OpenID Connect ou l'autorisation externe, avec un résumé d'une ligne pour chacun
Modifier une policy
- Trouvez la policy dans la liste
- Cliquez sur l'icône de modification
- Modifiez la configuration
- Cliquez sur Save
Seules les policies access control peuvent être modifiées dans l'interface aujourd'hui. Les policies connection settings et traffic & limits sont créées et supprimées, mais pas modifiées — remplacez-en une en la supprimant puis en la recréant.
Une policy que l'éditeur ne peut pas représenter sans perte est marquée View only, et la raison est indiquée sur la policy — par exemple qu'elle s'applique à plusieurs cibles, ou qu'elle utilise un paramètre sans formulaire correspondant. Cela arrive le plus souvent avec des policies créées ou modifiées en dehors de SailOps. Supprimez et recréez une telle policy pour la remettre sous le contrôle de l'éditeur, ou contactez le support.
Supprimer une policy
- Trouvez la policy dans la liste
- Cliquez sur l'icône de suppression
- Confirmez la suppression
Les policies portant le libellé Managed by SailOps ne peuvent pas être supprimées. Modifiez le paramètre qui contrôle la policy à la place.
Supprimer une policy supprime immédiatement les règles. Le trafic utilisera le comportement par défaut de la gateway. Si vous souhaitez uniquement empêcher une policy de s'appliquer à une route spécifique, utilisez l'action de détachement à la place.
Cas d'utilisation courants
Panel admin sécurisé
Restreindre l'accès admin aux IP internes :
| Paramètre | Valeur |
|---|---|
| Type | Access control |
| Nom | admin-whitelist |
| S'applique à | Route HTTP admin-route |
| Action par défaut | Deny |
Règles : Allow 10.0.0.0/8 (réseau interne uniquement)
Protection Rate API
Protéger une API avec un circuit breaker :
| Paramètre | Valeur |
|---|---|
| Type | Traffic & limits |
| Nom | api-protection |
| S'applique à | Route HTTP api-route |
Circuit Breaker : Max connexions : 200, Max requêtes en attente : 100
Retry : 2 retries sur erreurs 503
Backend Haute Disponibilité
Configurer des connexions résilientes vers votre application :
| Paramètre | Valeur |
|---|---|
| Type | Traffic & limits |
| Nom | ha-backend |
| S'applique à | Route HTTP critical-api |
Paramètres de timeout :
| Paramètre | Valeur |
|---|---|
| Request | 60s |
| Connect | 3s |
Paramètres de retry :
| Paramètre | Valeur |
|---|---|
| Nombre de retries | 3 |
| Timeout par retry | 15s |
| Retry sur | Erreurs serveur (5xx), Connexion impossible |
Circuit Breaker : Max connexions : 500
Dépannage
Policy non appliquée
- Vérifiez les avertissements de policy — une autre policy du même type couvre peut-être déjà la cible
- Vérifiez que la policy s'applique à la gateway ou la route attendue
- Assurez-vous que cette gateway ou route existe toujours
IP non bloquée/autorisée
- Vérifiez que la notation CIDR est correcte
- Vérifiez ce à quoi la policy s'applique
- Revoyez le paramètre d'action par défaut
Timeouts non fonctionnels
- Vérifiez que la policy s'applique à la bonne route
- Vérifiez que les valeurs de timeout sont raisonnables
- Assurez-vous que votre application est saine