Apache APISIX (apisix)

API gateway of the platform: TLS termination, routing to the Control Plane and the portal, rate limits; its routes are stored in etcd.

Generated from catalog/services/apisix.yaml: do not edit by hand.

Summary

Version	3.19.0
Use	install and configure, configure and connect
Layer	functional (AI catalog)
Category	Gateways and load balancing
Installation methods	package, podman
External connection	no
Sandbox only	no

Licence

SPDX identifier	Apache-2.0
Licence policy	core licence (MIT or Apache-2.0)
Licence exception	-
Platform component	apisix

Packages and artifacts

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

Kind	Package	Version	Licence	Details
container image	docker.io/apache/apisix	3.19.0-debian	Apache-2.0	image key apisix, used by apisix-gateway, digest sha256:9a7e45dc943fbf10ec916d1232bae4cda9302ae28a4696cfb83c2da01d261141
OS package	apisix	version of the configured repository	Apache-2.0	RHEL family (dnf)
OS package	apisix	version of the configured repository	Apache-2.0	Debian family (apt)

Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.

Supported systems and architectures

Method	Operating systems	Architectures
package	RHEL family (dnf), Debian family (apt)	x86_64, aarch64 (not restricted by the descriptor)
podman	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: 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). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites

Host

The descriptor declares no host preflight check.

Network and ports

Component	Port name	Port	Opened in the host firewall
apisix-gateway	http	9080/tcp	yes
apisix-gateway	https	9443/tcp	yes
apisix-gateway	admin	9180/tcp	yes
apisix-gateway	metrics	9091/tcp	yes
apisix-gateway	status	7085/tcp	no

Services and connections needed

• etcd: etcd.

Details and resolution: see Dependencies.

Installation methods and modes

Method	Default	What the method uses
package	yes	the OS packages of the descriptor, installed by the package manager of the host
podman	-	the container images of the descriptor, run by Podman under systemd

Components

Component	Kind	Installation methods	Ports
APISIX gateway (apisix-gateway)	master	package, podman	9080/tcp, 9443/tcp, 9180/tcp, 9091/tcp, 7085/tcp

Single gateway (standalone) (default)

One gateway node.

What the mode deploys:

Component	Placement
apisix-gateway	min 1, max 1

Replicated (replicated)

Several gateway nodes sharing etcd, behind HAProxy and keepalived.

What the mode deploys:

Component	Placement
apisix-gateway	min 2, recommended 2

Install this service

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

1. Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.

2. Choose the service. On the Service step, select Apache APISIX. The card shows the licence Apache-2.0 and the dependencies the installation needs. Pick the Method among package, podman (default package).

3. Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), replicated. Each mode deploys the components listed in Installation methods and modes.

4. Bind the dependencies. On the Bindings step, choose for each dependency (etcd) Install with the platform or Use an existing connection; an optional dependency can stay on No binding.

5. Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.

6. Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.

7. Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.

Connect an existing service

Schemes	https, http
Default port	9080
Authentication	required
Health check	status_url + /status/ready

Authentication method	Fields	Description
api_key	api_key	Admin API key (deployment.admin.admin_key), sent to the Admin API of the Admin API URL field.

Official documentation: https://apisix.apache.org/docs/apisix/admin-api/

Field	Type	Default	Description	Notes
Status API URL (status_url)	url	-	Status API URL of the existing service.	-
Admin API URL (admin_url)	url	-	Admin API URL of the existing service.	required

High availability

Cluster	replicas (replication)
High availability	external (external)
Failover	load balancer (load-balancer)
Replication	shared store (shared-store)
Quorum	none (none)
Discovery	none (none)
Entry point	load balancer (load-balancer)
Official documentation	https://apisix.apache.org/docs/apisix/installation-guide/

Prerequisites

Prerequisite	Must be highly available	Modes	Description
etcd	yes	modes of level ha or cluster	etcd holds the routes of every node: it needs its own Raft cluster (3 or 5 members).

Topology per mode

Modes	Highest catalog level	Distribution	Quorum component	Fault domains	Description
standalone	standalone (standalone)	single (single)	-	1	One instance, no fault tolerance.
replicated	ha (ha)	active-active (active-active)	-	2	Several gateway nodes reading the same configuration from etcd, behind HAProxy and keepalived.

Notes

• The gateway nodes do not talk to each other: their availability is the one of etcd and of the load balancer.

Configuration parameters

Network

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
HTTP port (http_port)	port	9080	-	no	no	yes	Plain HTTP listener of the gateway; with TLS it serves TLS too and no plain HTTP listener is left.
HTTPS port (https_port)	port	9443	-	no	no	yes	TLS listener of the gateway.
Admin API port (admin_port)	port	9180	-	no	no	yes	Admin API, reachable from the allowed networks only.
Metrics port (metrics_port)	port	9091	-	no	no	no	Prometheus exporter of the gateway.
Status port (status_port)	port	7085	-	no	no	no	Port of /status and /status/ready.

Security

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
TLS (tls_enabled)	bool	false	-	no	no	yes	Serve the gateway listeners, the admin API and the metrics over TLS with the certificate of the host issued by the manager CA (loaded as the SSL object navin-<host> of etcd for the gateway listeners). Required when etcd uses TLS: its certificate is also the etcd client certificate.
Admin networks (admin_allow)	list	["127.0.0.0/24"]	-	no	no	no	CIDR allowed to call the admin API.
Admin key (admin_key)	password	generated	-	no	yes	no	Key of the admin API (role admin).
etcd prefix (etcd_prefix)	string	/apisix	-	no	no	no	Key prefix of the gateway in etcd.

Dependencies

For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).

Binding	Provided by	Connection type	Endpoint	Optional	When nothing is bound	Description
etcd	etcd	-	client	no	etcd is added to the installation	Configuration store of the routes, upstreams and plugins.

Endpoints

Endpoint	Scheme	Component	Port	Path	TLS parameter	Binding parameters	Binding secrets	Provisioning command
gateway	http	apisix-gateway	9080 (http_port)	-	tls_enabled	-	-	-
admin	http	apisix-gateway	9180 (admin_port)	-	tls_enabled	-	token	-

Client configuration files

Files rendered for the client configuration download:

• apisix.env (client.env.j2)

Commands

Command	Component	Target	Description
Check the admin API (list_routes)	apisix-gateway	first host	Checks that the admin API answers (key required for the content).

Health checks

Liveness (per instance)

Component	Check	Details
apisix-gateway	HTTP http://127.0.0.1:{{ config.status_port }}/status/ready	Expected 200; 30 retries; interval 2 s; timeout 3 s
apisix-gateway	{{ paths.etc }}/gateway-cert.sh	30 retries; interval 2 s; timeout 30 s

Preflight checks

Check	Type	Meaning	Severity	Components
http_port_free	port_free {"param": "http_port"}	port 9080 free on the host	blocking	every component
admin_port_free	port_free {"param": "admin_port"}	port 9180 free on the host	blocking	every component

Uninstall

Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.

Quick links

• Dashboard: {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.admin_port }}/ui/
• Metrics: {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.metrics_port }}/apisix/prometheus/metrics

Upstream documentation

• Homepage: https://apisix.apache.org
• Source: https://github.com/apache/apisix
• High availability: https://apisix.apache.org/docs/apisix/installation-guide/
• Authentication: https://apisix.apache.org/docs/apisix/admin-api/