Apache APISIX (apisix)

Passerelle d'API de la plateforme : terminaison TLS, routage vers le Control Plane et le portail, limites de débit ; ses routes sont stockées dans etcd.

Généré depuis catalog/services/apisix.yaml : ne pas modifier à la main.

Résumé

Version	3.19.0
Usage	installer et configurer, configurer et connecter
Couche	fonctionnelle (catalogue IA)
Catégorie	Passerelles et répartition de charge
Méthodes d'installation	package, podman
Connexion externe	non
Réservé au bac à sable	non

Licence

Identifiant SPDX	Apache-2.0
Politique de licence	licence socle (MIT ou Apache-2.0)
Exception de licence	-
Composant de la plateforme	apisix

Paquets et artefacts

Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.

Type	Paquet	Version	Licence	Détails
image de conteneur	docker.io/apache/apisix	3.19.0-debian	Apache-2.0	clé d'image apisix, utilisée par apisix-gateway, condensé sha256:9a7e45dc943fbf10ec916d1232bae4cda9302ae28a4696cfb83c2da01d261141
paquet système	apisix	version du dépôt configuré	Apache-2.0	famille RHEL (dnf)
paquet système	apisix	version du dépôt configuré	Apache-2.0	famille Debian (apt)

Les images sont épinglées par étiquette dans le descripteur, et par condensé (digest) quand le descripteur en déclare un (le bundle hors ligne refuse alors une image téléchargée qui ne le porte pas) ; le condensé est enregistré dans le miroir du Manager à l'import du bundle hors ligne, et chaque téléchargement ou chargement est vérifié par rapport à lui.

Systèmes et architectures pris en charge

Méthode	Systèmes d'exploitation	Architectures
package	famille RHEL (dnf), famille Debian (apt)	x86_64, aarch64 (non restreintes par le descripteur)
podman	famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman)	x86_64, aarch64 (non restreintes par le descripteur)

Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.

Prérequis

Hôte

Le descripteur ne déclare aucun contrôle préalable de l'hôte.

Réseau et ports

Composant	Nom du port	Port	Ouvert dans le pare-feu de l'hôte
apisix-gateway	http	9080/tcp	oui
apisix-gateway	https	9443/tcp	oui
apisix-gateway	admin	9180/tcp	oui
apisix-gateway	metrics	9091/tcp	oui
apisix-gateway	status	7085/tcp	non

Services et connexions nécessaires

• etcd : etcd.

Détail et résolution : voir Dépendances.

Méthodes et modes d'installation

Méthode	Défaut	Ce que la méthode utilise
package	oui	les paquets système du descripteur, installés par le gestionnaire de paquets de l'hôte
podman	-	les images de conteneur du descripteur, exécutées par Podman sous systemd

Composants

Composant	Type	Méthodes d'installation	Ports
Passerelle APISIX (apisix-gateway)	maître	package, podman	9080/tcp, 9443/tcp, 9180/tcp, 9091/tcp, 7085/tcp

Passerelle unique (standalone) (par défaut)

Un seul nœud de passerelle.

Ce que le mode déploie :

Composant	Placement
apisix-gateway	min 1, max 1

Répliqué (replicated)

Plusieurs nœuds de passerelle qui partagent etcd, derrière HAProxy et keepalived.

Ce que le mode déploie :

Composant	Placement
apisix-gateway	min 2, recommandé 2

Installer ce service

L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.

1. Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.

2. Choisissez le service. À l'étape Service, sélectionnez Apache APISIX. La carte affiche la licence Apache-2.0 et les dépendances dont l'installation a besoin. Choisissez la Méthode parmi package, podman (par défaut package).

3. Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : standalone (par défaut), replicated. Chaque mode déploie les composants listés dans Méthodes et modes d'installation.

4. Liez les dépendances. À l'étape Liaisons, choisissez pour chaque dépendance (etcd) Installer avec la plateforme ou Utiliser une connexion existante ; une dépendance facultative peut rester sur Aucune liaison.

5. Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.

6. Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.

7. Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services.

Connecter un service existant

Schémas	https, http
Port par défaut	9080
Authentification	obligatoire
Contrôle de santé	status_url + /status/ready

Méthode d'authentification	Champs	Description
api_key	api_key	Clé de l'Admin API (deployment.admin.admin_key), envoyée à l'Admin API du champ URL de l'Admin API.

Documentation officielle : https://apisix.apache.org/docs/apisix/admin-api/

Champ	Type	Défaut	Description	Remarques
URL de l'API d'état (status_url)	url	-	URL de l'API d'état du service existant.	-
URL de l'API d'administration (admin_url)	url	-	URL de l'API d'administration du service existant.	obligatoire

Haute disponibilité

Cluster	réplicas (replication)
Haute disponibilité	externe (external)
Bascule	répartiteur (load-balancer)
Réplication	stockage partagé (shared-store)
Quorum	aucun (none)
Découverte	aucun (none)
Point d'entrée	répartiteur (load-balancer)
Documentation officielle	https://apisix.apache.org/docs/apisix/installation-guide/

Prérequis

Prérequis	Doit être hautement disponible	Modes	Description
etcd	oui	modes de niveau ha ou cluster	etcd porte les routes de tous les nœuds : il lui faut son propre cluster Raft (3 ou 5 membres).

Topologie par mode

Modes	Niveau le plus haut du catalogue	Répartition	Composant du quorum	Domaines de panne	Description
standalone	autonome (standalone)	unique (single)	-	1	Une instance, sans tolérance aux pannes.
replicated	ha (ha)	actif-actif (active-active)	-	2	Plusieurs nœuds de passerelle lisant la même configuration dans etcd, derrière HAProxy et keepalived.

Remarques

• Les nœuds de passerelle ne se parlent pas : leur disponibilité est celle d'etcd et du répartiteur.

Paramètres de configuration

Réseau

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Port HTTP (http_port)	port	9080	-	non	non	oui	Écouteur HTTP simple de la passerelle ; avec TLS il sert lui aussi du TLS et il ne reste aucun écouteur HTTP simple.
Port HTTPS (https_port)	port	9443	-	non	non	oui	Écouteur TLS de la passerelle.
Port de l'API d'administration (admin_port)	port	9180	-	non	non	oui	API d'administration, joignable depuis les réseaux autorisés uniquement.
Port des métriques (metrics_port)	port	9091	-	non	non	non	Exportateur Prometheus de la passerelle.
Port d'état (status_port)	port	7085	-	non	non	non	Port de /status et /status/ready.

Sécurité

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
TLS (tls_enabled)	bool	false	-	non	non	oui	Servir les écouteurs de la passerelle, l'API d'administration et les métriques en TLS avec le certificat de l'hôte émis par l'autorité de la console (chargé comme objet SSL navin-<hôte> d'etcd pour les écouteurs de la passerelle). Obligatoire quand etcd utilise TLS : son certificat est aussi le certificat client d'etcd.
Réseaux d'administration (admin_allow)	list	["127.0.0.0/24"]	-	non	non	non	CIDR autorisés à appeler l'API d'administration.
Clé d'administration (admin_key)	password	généré	-	non	oui	non	Clé de l'API d'administration (rôle admin).
Préfixe etcd (etcd_prefix)	string	/apisix	-	non	non	non	Préfixe des clés de la passerelle dans etcd.

Dépendances

Pour chaque dépendance active, le Manager prend la première solution parmi : la liaison choisie dans l'assistant ; un service de la même installation qui la fournit ; un service déjà installé dans le cluster ; la seule connexion du type attendu. Sinon, une dépendance facultative reste non liée, et une dépendance obligatoire est ajoutée à l'installation dans son mode par défaut (la colonne ci-dessous nomme le service du catalogue ajouté).

Liaison	Fournie par	Type de connexion	Point d'accès	Facultative	Quand rien n'est lié	Description
etcd	etcd	-	client	non	etcd est ajouté à l'installation	Stockage de configuration des routes, des services amont et des extensions.

Points d'accès

Point d'accès	Schéma	Composant	Port	Chemin	Paramètre TLS	Paramètres de liaison	Secrets de liaison	Commande de provisionnement
gateway	http	apisix-gateway	9080 (http_port)	-	tls_enabled	-	-	-
admin	http	apisix-gateway	9180 (admin_port)	-	tls_enabled	-	token	-

Fichiers de configuration client

Fichiers rendus pour le téléchargement de la configuration client :

• apisix.env (client.env.j2)

Commandes

Commande	Composant	Cible	Description
Vérifier l'API d'administration (list_routes)	apisix-gateway	premier hôte	Vérifie que l'API d'administration répond (clé exigée pour le contenu).

Contrôles de santé

Vivacité (par instance)

Composant	Contrôle	Détails
apisix-gateway	HTTP http://127.0.0.1:{{ config.status_port }}/status/ready	Attendu 200 ; 30 tentatives ; intervalle 2 s ; délai 3 s
apisix-gateway	{{ paths.etc }}/gateway-cert.sh	30 tentatives ; intervalle 2 s ; délai 30 s

Contrôles préalables

Contrôle	Type	Signification	Sévérité	Composants
http_port_free	port_free {"param": "http_port"}	port 9080 libre sur l'hôte	bloquant	tous les composants
admin_port_free	port_free {"param": "admin_port"}	port 9180 libre sur l'hôte	bloquant	tous les composants

Désinstallation

Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.

Liens rapides

• Tableau de bord : {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.admin_port }}/ui/
• Métriques : {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.metrics_port }}/apisix/prometheus/metrics

Documentation amont

• Site : https://apisix.apache.org
• Sources : https://github.com/apache/apisix
• Haute disponibilité : https://apisix.apache.org/docs/apisix/installation-guide/
• Authentification : https://apisix.apache.org/docs/apisix/admin-api/