Aller au contenu principal

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
Référence technique

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
info

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ètreValeur
Nomapi-whitelist
S'applique àRoute HTTP api-route
Action par défautDeny

Règles :

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

ÉtatSignification
ValidLes notes sont cohérentes et peuvent être modifiées normalement
AmbiguousLes 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.
UnsupportedLes 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 à 0 pour le désactiver.
ParamètreValeur
Nomsecure-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ètreValeur
Nomresilient-backend
S'applique àRoute HTTP api-route

Paramètres de timeout :

ParamètreValeur
Timeout de requête30s
Timeout de connexion5s

Paramètres de retry :

ParamètreValeur
Nombre de retries3
Retry surErreurs serveur (5xx), Connexion impossible

Circuit Breaker :

ParamètreValeur
Max connexions100
Max requêtes en attente50

Créer une policy​

Étape par étape​

  1. Allez dans votre gateway
  2. Cliquez sur l'onglet Policies
  3. Cliquez sur Create Policy
  4. Sélectionnez le type de policy
  5. Configurez :
ChampDescriptionExemple
NomIdentifiant uniqueapi-security
TypeType de policyAccess control
S'applique àLa gateway ou la route couverte par les règlesRoute HTTP api-route
ConfigurationParamètres spécifiques à la policyVoir ci-dessous
  1. 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 policyPeut s'appliquer à
Access controlGateway, route HTTP, route gRPC, route TCP
Connection settingsGateway uniquement
Traffic & limitsGateway, route HTTP, route gRPC, route TCP, route TLS, route UDP

Appliquer à une gateway​

Les règles couvrent tout le trafic passant par la gateway :

ChampValeur
S'applique àGateway
Nommy-gateway

Appliquer à une route​

Les règles couvrent une route spécifique :

ChampValeur
S'applique àRoute HTTP
Nomapi-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 »​

Le filtrage IP nécessite l'IP réelle du client

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ètreValeur
Nominternal-only
S'applique àRoute HTTP admin-route
Action par défautDeny

Règles :

ActionCIDRNote
Allow10.0.0.0/8Réseau interne
Allow172.16.0.0/12Plage VPN

Liste noire d'IP​

Bloquer des plages d'IP spécifiques :

ParamètreValeur
Nomblock-bad-actors
S'applique àGateway my-gateway
Action par défautAllow

Règles :

ActionCIDRNote
Deny203.0.113.0/24Plage connue comme malveillante

Notation CIDR​

Patterns CIDR courants :

CIDRDescription
10.0.0.0/8Réseau privé (Classe A)
172.16.0.0/12Réseau privé (Classe B)
192.168.0.0/16Réseau privé (Classe C)
0.0.0.0/0Toutes les adresses IPv4
203.0.113.5/32Une seule adresse IP

Configuration « Connection settings »​

Paramètres HTTP/2​

Activer HTTP/2 pour de meilleures performances :

ParamètreValeur
Nomhttp2-enabled
S'applique àGateway my-gateway
HTTP/2 activétrue
Max streams concurrents100

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ètreValeur
Nomtimeout-policy
S'applique àRoute HTTP api-route

Paramètres de timeout :

ParamètreValeurDescription
Request30sTimeout total de requête
Connect5sTimeout de connexion
Idle60sTimeout de connexion inactive

Retries​

Retry automatique sur échecs :

ParamètreValeur
Nomretry-policy
S'applique àRoute HTTP api-route

Paramètres de retry :

ParamètreValeur
Nombre de retries3
Timeout par retry10s
Retry surErreurs serveur (5xx), Connexion impossible, Connexion réinitialisée

Circuit Breaker​

Protéger votre application contre la surcharge :

ParamètreValeur
Nomcircuit-breaker
S'applique àRoute HTTP api-route

Paramètres du Circuit Breaker :

ParamètreValeur
Max connexions100
Max requêtes en attente50
Max requêtes1000

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ètreValeur
Requêtes100
Unité de tempsSecond, 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ètreDescription
RequêtesNombre maximum de requêtes dans la fenêtre de temps
Unité de tempsSecond, Minute, Hour, Day, Month ou Year
Client SelectorsRè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électeurDescriptionExemple
CIDRCorrespondance par plage d'IP source192.168.1.0/24
Header (Exact)Correspondance avec une valeur de header spécifiqueX-Tenant: acme
Header (Regex)Correspondance quand un header correspond à un pattern regexUser-Agent: .*bot.*
Header (Distinct)Crée un compteur de rate-limit séparé pour chaque valeur unique du headerX-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.

astuce

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.

  1. Allez sur la page de détail de la route
  2. Trouvez la policy dans la section Attached Policies
  3. Cliquez sur l'icône de détachement
  4. Confirmez l'action
info

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.

info

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.

ÉtatLibellé dans l'interfaceSignification
ActiveActiveLa policy est en vigueur sur toutes les cibles auxquelles elle s'applique.
PartialPartly appliedLa policy est en vigueur sur certaines cibles mais pas toutes.
NotAppliedNot appliedLa policy n'est en vigueur sur aucune de ses cibles.
UnconfirmedNot confirmedSailOps n'a pas confirmé si cette policy est en vigueur. C'est normal pour une policy fraîchement créée.
NeedsAttentionNeeds attentionUne 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 :

TagAffiché quand
Deny by default · N allow rules · M deny rulesRègles d'autorisation avec une action par défaut explicite
IP filteringRègles d'autorisation filtrant par CIDR client
CORSCORS est configuré
JWTAuthentification JWT est configurée
Basic authL'authentification HTTP Basic est configurée
N req/unitRate limiting avec une limite spécifique (par ex. « 100 req/minute »)
Sticky (consistent hash)Load balancing en consistent hash
N retriesNombre de retries
Timeout XsValeur 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.

AvertissementCodeSignification
Not appliedPOLICY_CONFLICTEDUne autre policy du même type s'applique déjà à cette cible. Celle-ci est ignorée.
OverriddenPOLICY_OVERRIDDENUne policy appliquée directement à la route est prioritaire ; celle-ci n'a donc aucun effet.
Not acceptedPOLICY_NOT_ACCEPTEDSailOps n'a pas pu appliquer cette policy. Vérifiez ses paramètres, ou contactez le support.
Client IP not preservedCLIENT_IP_PRESERVATION_DISABLEDLa 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.

astuce

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​

  1. Trouvez la policy dans la liste
  2. Cliquez sur l'icône de modification
  3. Modifiez la configuration
  4. Cliquez sur Save
info

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.

info

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​

  1. Trouvez la policy dans la liste
  2. Cliquez sur l'icône de suppression
  3. Confirmez la suppression
info

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.

attention

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ètreValeur
TypeAccess control
Nomadmin-whitelist
S'applique àRoute HTTP admin-route
Action par défautDeny

Règles : Allow 10.0.0.0/8 (réseau interne uniquement)

Protection Rate API​

Protéger une API avec un circuit breaker :

ParamètreValeur
TypeTraffic & limits
Nomapi-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ètreValeur
TypeTraffic & limits
Nomha-backend
S'applique àRoute HTTP critical-api

Paramètres de timeout :

ParamètreValeur
Request60s
Connect3s

Paramètres de retry :

ParamètreValeur
Nombre de retries3
Timeout par retry15s
Retry surErreurs serveur (5xx), Connexion impossible

Circuit Breaker : Max connexions : 500

Dépannage​

Policy non appliquée​

  1. Vérifiez les avertissements de policy — une autre policy du même type couvre peut-être déjà la cible
  2. Vérifiez que la policy s'applique à la gateway ou la route attendue
  3. Assurez-vous que cette gateway ou route existe toujours

IP non bloquée/autorisée​

  1. Vérifiez que la notation CIDR est correcte
  2. Vérifiez ce à quoi la policy s'applique
  3. Revoyez le paramètre d'action par défaut

Timeouts non fonctionnels​

  1. Vérifiez que la policy s'applique à la bonne route
  2. Vérifiez que les valeurs de timeout sont raisonnables
  3. Assurez-vous que votre application est saine

Sujets connexes​