This is an automated email from the ASF dual-hosted git repository.
Yilialinn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new 363335c133d content: update six GSC-priority gateway guides (#2109)
363335c133d is described below
commit 363335c133d7626ced5efe57badb5fb5fec64ce7
Author: Yilia Lin <[email protected]>
AuthorDate: Thu Aug 27 17:35:09 2026 +0800
content: update six GSC-priority gateway guides (#2109)
---
...onnect-Plugin-for-Centralized-Authentication.md | 304 +++++++-----------
.../blog/2021/12/30/apisix-proxy-grpc-service.md | 232 ++++++--------
.../11/07/webhook-api-gateway-event-driven-apis.md | 172 +++++++---
.../19/why-do-microservices-need-an-api-gateway.md | 155 +++++----
blog/en/blog/2023/10/07/apisix-gitops-adc.md | 354 ++++++++-------------
...ud-vs-open-source-vs-commercial-api-gateways.md | 169 +++++-----
6 files changed, 646 insertions(+), 740 deletions(-)
diff --git
a/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md
b/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md
index 5173657e028..929129de25e 100644
---
a/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md
+++
b/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md
@@ -12,255 +12,177 @@ authors:
image_url: "https://avatars.githubusercontent.com/u/36651058?v=4";
keywords:
- API Gateway
- - APISIX
- Apache APISIX
- - Okta
- - Authorization
-description: Simplify API authentication by using the APISIX openid-connect
plugin to centralize identity verification at the gateway level.
+ - OpenID Connect
+ - OIDC Authentication
+ - Centralized Authentication
+description: "Learn how the APISIX openid-connect plugin validates tokens or
runs the OIDC authorization code flow before proxying requests upstream."
tags: [Authentication, Plugins, Ecosystem]
image: https://static.apiseven.com/2022/blog/0818/plugins/openid%20connect.png
---
-> Compared with the traditional authentication mode, the centralized
authentication mode has the following advantages: first, it simplifies the
application development process, reduces the development application workload
and maintenance costs, and avoids repeated development of authentication code
for each application; second, it improves business security, and the
centralized authentication mode can intercept unauthenticated requests at the
gateway level in time to protect back-end app [...]
+The Apache APISIX `openid-connect` plugin can integrate gateway routes with an
OpenID Connect identity provider. It can validate bearer tokens for API clients
or run the authorization code flow for browser-based applications. This
centralizes supported authentication checks at the gateway while leaving
resource-level authorization in the application that owns the data.
<!--truncate-->
-## What is Apache APISIX
+## OpenID Connect in an API Gateway
-[Apache APISIX](https://apisix.apache.org/) is a dynamic, real-time,
high-performance API gateway that provides rich traffic management features
such as load balancing, dynamic upstream, canary release, service meltdown,
authentication, observability, and more. Apache APISIX's OpenID Connect plug-in
supports OpenID, which allows users to replace authentication from traditional
authentication mode to centralized authentication mode.
+[OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) is
an identity layer built on OAuth 2.0. An identity provider publishes metadata,
authorization and token endpoints, and signing keys. A relying party validates
the resulting tokens and their claims.
-## What is authentication
+When APISIX protects a route, it acts as an OIDC relying party or
token-validating resource-server component, depending on the configured mode:
-Authentication refers to the verification of a user's identity through certain
means. The application identifies the user through authentication and obtains
detailed user metadata from the Identity Provider based on the user identity
ID, and uses it to determine whether the user has access to the specified
resources. Authentication modes are divided into two categories: **Traditional
Authentication Mode** and **Centralized Authentication Mode**.
+- **Authorization code flow:** a browser without an authenticated session is
redirected to the identity provider. APISIX processes the callback, establishes
a session, and then proxies the request.
+- **Bearer-only mode:** an API client sends an access token. APISIX validates
the token and rejects missing or invalid credentials instead of redirecting the
client.
-### Traditional authentication mode
+These modes serve different clients. Redirecting a machine client to a login
page is usually incorrect; accepting bearer tokens without the intended issuer,
audience, scope, and signature checks is unsafe.
-In traditional authentication mode, each application service needs to support
authentication separately, such as accessing the login interface when the user
is not logged in, and the interface returns a 301 jump page. The application
needs to develop the logic for maintaining the Session and the authentication
interaction with the identity provider. The flow of the traditional
authentication model is shown in the figure below: first, the user initiates a
request, then the gateway receive [...]
+## What Centralized Authentication Does—and Does Not—Do
-
+Applying authentication at the gateway can:
-### Centralized authentication mode
+- give multiple routes a consistent integration with the same identity
provider;
+- reject unauthenticated traffic before it reaches an upstream service;
+- reduce repeated OIDC protocol handling in individual edge-facing
applications;
+- attach validated token information to a trusted upstream request when
configured.
-Unlike the traditional authentication model, the centralized authentication
model takes user authentication out of the application service. Take Apache
APISIX as an example, the centralized authentication process is shown in the
following diagram: first, the user initiates a request, and then the front
gateway is responsible for the user authentication process, interfacing with
the identity provider and sending the identity provider an authorization)
request to the identity provider. The [...]
+It does not automatically implement all authorization. A valid identity may
still be unable to read a specific account, change another user's resource, or
perform an administrative action. Services should enforce domain- and
resource-level permissions using trusted identity context.
-
+The upstream must also be unable to receive spoofed identity headers directly
from an untrusted client. Restrict upstream network access and configure the
trusted proxy boundary so that only APISIX sets or forwards the identity
headers the application consumes.
-Compared with the traditional authentication mode, the centralized
authentication mode has the following advantages.
+## Prerequisites
-1. simplify the application development process, reduce the development of
application workload and maintenance costs, to avoid the repeated development
of each application authentication code.
-2. improve business security, centralized authentication mode at the gateway
level to intercept unauthenticated requests in time to protect the back-end
applications.
+Before configuring the plugin:
-## What is OpenID
+1. Create an OIDC client at the identity provider.
+2. Record the issuer's discovery URL, normally ending in
`/.well-known/openid-configuration`.
+3. Register the exact redirect URI used by APISIX for an authorization code
flow.
+4. Decide which scopes and claims the API requires.
+5. Store the client secret and session secret in protected configuration; do
not commit production values to source control.
+6. Ensure APISIX can reach the discovery, authorization, token,
user-information, and key endpoints required by the selected flow.
-OpenID is a centralized authentication model, which is a decentralized
identity system. The benefit of using OpenID is that users only need to
register and log in with one OpenID identity provider's website and use one
account password information to access different applications. okta is a common
OpenID identity provider and the Apache APISIX OpenID Connect plugin supports
OpenID so users can use the plugin to to replace the traditional authentication
model with a centralized authentica [...]
+Use HTTPS for the identity provider and public application route. The plugin's
TLS verification should remain enabled; the current default for `ssl_verify` is
`true`.
-### OpenID Authentication Process
+## Configure Authorization Code Flow
-The OpenID authentication process has the following 7 steps, as shown in the
figure below. 1.
-
-1. APISIX initiates an authentication request to Identity Provider. 2.
-2. The user logs in and authenticates on the Identity Provider. 3.
-3. The Identity Provider returns to APISIX with the Authorization Code. 4.
-4. APISIX requests the Identity Provider with the Code extracted from the
request parameters. 5.
-5. The Identity Provider sends an answer message to APISIX containing the ID
Token and Access Token. 6.
-6. APISIX sends the Access Token to the Identity Provider's User Endpoint to
obtain the user's identity.
-7. After authentication, the User Endpoint sends the User info to APISIX to
complete the authentication.
-
-
-
-## How to configure Okta authentication using the OpenID Connect plugin for
Apache APISIX
-
-Configuring Okta authentication using the Apache APISIX OpenID Connect plug-in
is a simple three-step process that allows you to switch from traditional to
centralized authentication mode. The following section describes the steps to
configure Okta authentication using the OpenID Connect plug-in for Apache
APISIX.
-
-### Prerequisites
-
-An Okta account already exists.
-
-### Step 1: Configure Okta
-
-1. Login to your Okta account and create an Okta application, select the OIDC
login mode and the Web Application application type.
- 
- 
2.
-2. Set the login and logout jump URLs.
-The "Sign-in redirect URIs" are the links that are allowed to be redirected
after successful login, and the "Sign-out redirect URIs" are the links that are
redirected after logging out. In this example, we set both the sign-in redirect
and sign-out redirect URLs to `http://127.0.0.1:9080/`.
- 
-3. Click "Save" to save the changes after finishing the settings.
- 
-Visit the General page of the application to get the following configuration,
which is required to configure Apache APISIX OpenID Connect.
-
-- Client ID: OAuth client ID, which is the ID of the application,
corresponding to `client_id` and `{YOUR_CLIENT_ID}` below.
-- Client secret: OAuth client secret, i.e. application key, corresponds to
`client_secret` and `{YOUR_CLIENT_SECRET}` below.
-- Okta domain: The domain name used by the application, corresponds to
`{YOUR_ISSUER}` in discovery below.
-
-
-
-### Installing Apache APISIX
-
-You can install Apache APISIX in a variety of ways such as through source
packages, Docker, Helm Chart, etc.
-
-#### Installing dependencies
-
-The Apache APISIX runtime environment requires dependencies on NGINX and etcd,
so before installing Apache APISIX, please install the corresponding
dependencies according to the operating system you are using. We have provided
steps for installing dependencies on CentOS7, Fedora 31 & 32, Ubuntu 16.04 &
18.04, Debian 9 & 10 and MacOS, please refer to [Installing
dependencies](https://apisix.apache.org/zh/docs/apisix/install) for details.
-dependencies/).
-
-When installing Apache APISIX via Docker or Helm Chart, the required NGINX and
etcd are already included, please refer to the respective documentation.
-
-#### Installation via RPM package (CentOS 7)
-
-This installation method is available for CentOS 7 operating system, please
run the following command to install Apache APISIX.
+The following Admin API request illustrates the relevant fields. Replace the
example identifiers and upstream with values from your environment.
```shell
-sudo yum install -y
https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
+curl "http://127.0.0.1:9180/apisix/admin/routes/oidc-browser"; \
+ -X PUT \
+ -H "X-API-KEY: $admin_key" \
+ -d '
+{
+ "uri": "/app/*",
+ "plugins": {
+ "openid-connect": {
+ "client_id": "<oidc-client-id>",
+ "client_secret": "<oidc-client-secret>",
+ "discovery": "https://id.example.com/.well-known/openid-configuration";,
+ "redirect_uri": "https://gateway.example.com/app/oidc/callback";,
+ "logout_path": "/app/logout",
+ "scope": "openid profile",
+ "bearer_only": false,
+ "realm": "example",
+ "session": {
+ "secret": "<random-secret-at-least-16-characters>"
+ }
+ }
+ },
+ "upstream_id": "app-service"
+}'
```
-#### Installation via Docker
+When `bearer_only` is `false`, the session secret is required and must contain
at least 16 characters. Use a high-entropy secret appropriate for the
deployment's secret-management system rather than the placeholder shown above.
-For details, please refer to: [Installing Apache APISIX with
Docker](https://hub.docker.com/r/apache/apisix).
+The example uses a fixed callback under the protected `/app/*` route. Replace
the hostname with the externally reachable gateway hostname and register
`https://gateway.example.com/app/oidc/callback` exactly with the identity
provider. Do not omit `redirect_uri` on a wildcard browser route: the default
is derived from the current request URI and would produce a different callback
path for different application pages. The explicit callback must remain a
subpath of the protected route witho [...]
-#### Installation via Helm Chart
+The explicit `/app/logout` path also remains inside the route matched by
`/app/*`. If you choose another logout path, ensure that a route carrying the
same plugin configuration matches it.
-For details, please refer to: [Installing Apache APISIX with Helm
Chart](https://github.com/apache/apisix-helm-chart).
+After successful login, APISIX maintains the configured session and proxies
the request. Test login, logout, session expiry, callback errors, and behavior
across multiple gateway instances before production rollout.
-#### Installation via source package
+## Configure Bearer-Only Token Validation
-1. Create a directory named ``apisix-2.7``.
-
- ```shell
- mkdir apisix-2.7
- ```
-
-2. Download the Apache APISIX Release source package.
-
- ```shell
- wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
- ```
-
- You can also download the Apache APISIX Release source package from the
Apache APISIX official website. The Apache APISIX official website also
provides source packages for Apache APISIX, APISIX Dashboard, and APISIX
Ingress Controller, see [Apache APISIX official website - download
page](https://apisix.apache.org/zh/ For details, please refer to the [Apache
APISIX official-downloads page](https://apisix.apache.org/downloads).
-
-3. Unpack the Apache APISIX Release source package.
-
- ```shell
- tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
- ```
-
-4. install the runtime dependencies of the Lua library:
-
- ```shell
- # Switch to the apisix-2.7 directory
- cd apisix-2.7
- # Create dependencies
- make deps
- ```
-
-#### Initializing dependencies
-
-Run the following command to initialize the NGINX configuration file and etcd.
+For APIs called with access tokens, enable bearer-only mode:
```shell
-# initialize NGINX config file and etcd
-make init
+curl "http://127.0.0.1:9180/apisix/admin/routes/oidc-api"; \
+ -X PUT \
+ -H "X-API-KEY: $admin_key" \
+ -d '
+{
+ "uri": "/api/*",
+ "plugins": {
+ "openid-connect": {
+ "client_id": "<api-client-id>",
+ "client_secret": "<api-client-secret>",
+ "discovery": "https://id.example.com/.well-known/openid-configuration";,
+ "scope": "openid",
+ "required_scopes": ["api.read"],
+ "claim_validator": {
+ "audience": {
+ "required": true,
+ "match_with_client_id": true
+ }
+ },
+ "bearer_only": true,
+ "realm": "example"
+ }
+ },
+ "upstream_id": "api-service"
+}'
```
-### Start Apache APISIX and configure the corresponding routes
-
-1. Run the following command to start Apache APISIX. 2.
-
-2. Create routes and configure the OpenID Connect plug-in.
+The `required_scopes` field makes the plugin reject a validated access token
that lacks `api.read`. The audience validator requires an `aud` claim and, in
this example, requires it to contain `<api-client-id>`. Configure the identity
provider so that this client ID is the access token's intended audience. If the
provider uses a separate API audience, use a supported validation rule that
matches that exact audience rather than disabling the check. Do not treat an ID
token intended for a b [...]
-The OpenID Connect configuration list is as follows.
+## Identity Information Sent Upstream
-|fields|default|description|
-| :------| :------------ | :------- |
-|client_id|""|OAuth client ID|
-|client_secret|""|OAuth client key|
-|discovery|""|the identity provider's service discovery endpoint|
-|scope|openid|scope of resources to be accessed|
-|relm|apisix|specifies the WWW-Authenticate response header authentication
information|
-|bearer_only|false|whether to check the token in the request header|
-|logout_path|/logout|logout URI|
-|redirect_uri|request_uri|The URI that the identity provider jumped back to,
defaulting to the request address|
-|timeout|3|The request timeout in seconds|
-|ssl_verify|false|whether the identity provider verifies the ssl certificate|
-|introspection_endpoint|""|the URL of the identity provider's token
verification endpoint, which will be extracted from the discovery response if
not filled|
-|introspection_endpoint_auth_method|client_secret_basic|the name of the
token's default authentication method|
-|public_key|""|public key of the authentication token|
-|token_signing_alg_values_expected|""|the algorithm for authenticating tokens|
-|set_access_token_header|true|whether to carry the access token in the request
header|
-|access_token_in_authorization_header|false|Place the access token in the
Authorization header if true, or in the X-Access-Token header if false|
-|set_id_token_header|true|whether to carry the ID token in the X-ID-Token
request header|
-|set_userinfo_header|true|whether to carry user information in the X-Userinfo
request header|
+The plugin can place access-token, ID-token, or user-information data in
upstream headers through its documented configuration options. Forward only the
data the upstream requires:
-The following code example creates a route through the Apache APISIX Admin
API, setting the route upstream to httpbin.org. httpbin.org is a simple backend
service for receiving and responding to requests, and the get page of
httpbin.org is used below, see [http bin get](
http://httpbin.org/#/HTTP_Methods/get_get).
+- avoid sending tokens to services that do not need them;
+- ensure clients cannot bypass APISIX and inject trusted headers;
+- redact credentials and token-bearing headers from access and error logs;
+- keep authorization decisions tied to stable claims such as issuer, subject,
audience, and approved scopes rather than mutable display fields.
-Please refer to [Apache APISIX OpenID Connect
Plugin](https://apisix.apache.org/zh/docs/apisix/plugins/openid-connect/) for
specific configuration items.
+An upstream service should fail closed when required trusted identity context
is absent or malformed.
-```shell
-curl -XPOST 127.0.0.1:9080/apisix/admin/routes -H "X-Api-Key:
edd1c9f034335f136f87ad84b625c8f1" -d '{
- "uri":"/*",
- "plugins":{
- "openid-connect":{
- "client_id":"{YOUR_CLIENT_ID}",
- "client_secret":"{YOUR_CLIENT_SECRET}",
-
"discovery":"https://{YOUR_ISSUER}/.well-known/openid-configuration";,
- "scope":"openid profile",
- "bearer_only":false,
- "realm":"master",
- "introspection_endpoint_auth_method":"client_secret_post",
- "redirect_uri": "http://127.0.0.1:9080/";
- }
- },
- "upstream":{
- "type": "roundrobin",
- "nodes":{
- "httpbin.org:80":1
- }
- }
-}'
-```
+## Operational and Security Checks
-### Step 4: Accessing Apache APISIX
+### Protect secrets and administrative access
-1. Visit http://127.0.0.1:9080/get and the page is redirected to the Okta
login page because the OpenID Connect plugin is turned on.
-
-
-
-2. Enter the password you registered with Okta and click "Sign in" to log in
to your Okta account. 3.
+Restrict access to the APISIX Admin API and configuration store. Use the
deployment's supported secret-management approach, limit who can read OIDC
credentials, and rotate client and session secrets through a tested procedure.
-3. After successful login, you can successfully access the get page in
httpbin.org. The httpbin.org/get page will return the requested data as follows.
+### Validate failure behavior
- ```sh
- "X-Access-Token":
"******Y0RPcXRtc0FtWWVuX2JQaFo1ZVBvSlBNdlFHejN1dXY5elV3IiwiYWxnIjoiUlMyNTYifQ.***TVER3QUlPbWZYSVRzWHRxRWh2QUtQMWRzVDVGZHZnZzAiLCJpc3MiOiJodHRwczovL3FxdGVzdG1hbi5va3RhLmNvbSIsImF1ZCI6Imh0dHBzOi8vcXF0ZXN0bWFuLm9rdGEuY29tIiwic3ViIjoiMjgzMDE4Nzk5QHFxLmNvbSIsImlhdCI6MTYyODEyNjIyNSwiZXhwIjoxNjI4MTI5ODI1LCJjaWQiOiIwb2ExMWc4ZDg3TzBGQ0dYZzY5NiIsInVpZCI6IjAwdWEwNWVjZEZmV0tMS3VvNjk1Iiwic2NwIjpbIm9wZW5pZCIsInByb2Zpb***.****iBshIcJhy8QNvzAFD0fV4gh7OAdTXFMu5k0hk0JeIU6Tfg_Mh-josfap3
[...]
- "X-Id-Token":
"******aTdDRDJnczF5RnlXMUtPZUtuSUpQdyIsImFtciI6WyJwd2QiXSwic3ViIjoiMDB1YTA1ZWNkRmZXS0xLdW82OTUiLCJpc3MiOiJodHRwczpcL1wvcXF0ZXN0bWFuLm9rdGEuY29tIiwiYXVkIjoiMG9hMTFnOGQ4N08wRkNHWGc2OTYiLCJuYW1lIjoiUGV0ZXIgWmh1IiwianRpIjoiSUQuNGdvZWo4OGUyX2RuWUI1VmFMeUt2djNTdVJTQWhGNS0tM2l3Z0p5TTcxTSIsInZlciI6MSwicHJlZmVycmVkX3VzZXJuYW1lIjoiMjgzMDE4Nzk5QHFxLmNvbSIsImV4cCI6MTYyODEyOTgyNSwiaWRwIjoiMDBvYTA1OTFndHAzMDhFbm02OTUiLCJub25jZSI6ImY3MjhkZDMxMWRjNGY3MTI4YzlmNjViOGYzYjJkMDgyIiwiaWF0IjoxN
[...]
- "X-Userinfo":
"*****lfbmFtZSI6IlpodSIsImxvY2FsZSI6ImVuLVVTIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiMjgzMDE4Nzk5QHFxLmNvbSIsInVwZGF0ZWRfYXQiOjE2MjgwNzA1ODEsInpvbmVpbmZvIjoiQW1lcmljYVwvTG9zX0FuZ2VsZXMiLCJzdWIiOiIwMHVhMDVlY2RGZldLTEt1bzY5NSIsImdpdmVuX25hbWUiOiJQZXRlciIsIm5hbWUiOiJQZXRl****"
- ```
+Test expired tokens, invalid signatures, missing scopes, identity-provider
outages, key rotation, clock skew, and discovery refresh. Decide whether each
protected route should reject traffic or use another explicit behavior when
identity services are unavailable.
-In which:
+### Separate authentication from authorization
-**X-Access-Token**: Apache APISIX puts the access token obtained from the user
provider into the X-Access-Token request header, which can be optionally put
into the Authorization request header via access_token_in_authorization_header
in the plugin configuration.
+The gateway can require a valid token and selected scopes. The service should
still check tenant, object ownership, role, and business-state constraints.
Document which layer owns every decision so a policy is neither omitted nor
inconsistently duplicated.
-
+### Monitor without leaking credentials
-**X-Id-Token**: Apache APISIX will put the ID token obtained from the user
provider into the X-Id-Token request header after base64 encoding, you can
choose whether to enable this feature by using the set_id_token_header in the
plugin configuration.
+Measure authentication success and failure rates, identity-provider latency,
callback errors, and session failures. Avoid labels containing raw subject IDs
or tokens, and never log client secrets, authorization codes, or complete
bearer tokens.
-
+## Frequently Asked Questions
-**X-Userinfo**: Apache APISIX will get the user information from the user
provider and put it into X-Userinfo after base64 encoding, you can choose
whether to turn it on or not by using set_userinfo_header in the plugin
configuration, the default is on.
+### Is OpenID the same as OpenID Connect?
-
+No. This integration uses OpenID Connect, the modern identity protocol built
on OAuth 2.0. The APISIX plugin is named `openid-connect`.
-As you can see, Apache APISIX will carry the X-Access-Token, X-Id-Token, and
X-Userinfo request headers to the upstream. The upstream can parse these
headers to get the user ID information and user metadata.
+### Should every route use authorization code flow?
-We show the process of setting up centralized authentication from Okta
directly in Apache APISIX. It is easy to get started by signing up for a free
Okta developer account. This centralized approach to authentication reduces
learning and maintenance costs for developers and provides a secure and
streamlined user experience.
+No. It is suitable for interactive browser login. APIs called by software
clients commonly use bearer-only token validation or another appropriate
authentication method.
-## About Okta
+### Does validating a token at APISIX secure the upstream by itself?
-Okta is a customizable, secure centralized authentication solution. Okta can
add authentication and authorization to your application. Get scalable
authentication directly in your application without writing your own code. You
can connect your application to Okta and define how users log in. Each time a
user tries to authenticate, Okta verifies their identity and sends the required
information back to your application.
+No. The upstream network path, trusted header boundary, resource
authorization, secret handling, and service-to-service access must also be
secured.
-## About Apache APISIX
+### Where is the complete configuration reference?
-Apache APISIX is a dynamic, real-time, high-performance API gateway that
provides load balancing, dynamic upstream, canary release, service meltdown,
authentication, observability, and other rich traffic management features. You
can use Apache APISIX for traditional north-south traffic, as well as east-west
traffic between services, or as a [Kubernetes Ingress
Controller](https://github.com/apache/apisix-ingress-controller).
+Use the current [`openid-connect` plugin
documentation](https://apisix.apache.org/docs/apisix/plugins/openid-connect/)
as the source of truth for supported fields, defaults, examples, and
version-specific behavior.
-Hundreds of enterprises worldwide have used Apache APISIX to handle
business-critical traffic, covering finance, Internet, manufacturing, retail,
carriers, and more, such as NASA, the EU's Digital Factory, China Airlines,
China Mobile, Tencent, Huawei, Sina Weibo, NetEase, Ke, 360, Taikang, Nayuki,
and more.
+## Conclusion
-Github: https://github.com/apache/apisix
+The APISIX `openid-connect` plugin can centralize OIDC authentication for
browser and API routes. Choose the correct flow, register the callback
precisely, validate the issuer and token requirements, protect secrets, and
keep resource-level authorization in the service that owns the resource.
-Official website: https://apisix.apache.org
+Treat the gateway as one layer in the identity architecture—not as a
replacement for upstream authorization or a reason to trust unprotected
identity headers.
diff --git a/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md
b/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md
index 441667fb157..154392040b3 100644
--- a/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md
+++ b/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md
@@ -1,5 +1,5 @@
---
-title: "Use API gateway to proxy gRPC service"
+title: "Proxy HTTP Requests to gRPC with APISIX grpc-transcode"
authors:
- name: "Bozhong Yu"
title: "Author"
@@ -9,183 +9,163 @@ authors:
title: "Technical Writer"
url: "https://github.com/SylviaBABY";
image_url: "https://avatars.githubusercontent.com/u/39793568?v=4";
-keywords:
-- Apache APISIX
-- gRPC
-- Google
-- proto
-- plugin
-description: This article shows you how to proxy client HTTP traffic to the
back-end gRPC service via the `grpc-transcode` plugin in API Gateway Apache
APISIX.
+keywords:
+ - Apache APISIX
+ - gRPC
+ - grpc-transcode
+ - API Gateway
+ - Protocol Buffers
+description: "Configure the APISIX grpc-transcode plugin to translate an HTTP
request into a unary gRPC call using a registered Protocol Buffers definition."
tags: [Ecosystem]
---
-> This article shows you how to proxy client HTTP traffic to the back-end gRPC
service via the `grpc-transcode` plugin in Apache APISIX.
+Apache APISIX can proxy native gRPC traffic, translate gRPC-Web for browser
clients, or transcode an HTTP request into a gRPC call. These are different use
cases. This tutorial focuses on HTTP-to-gRPC transcoding with the
`grpc-transcode` plugin.
<!--truncate-->
-## Introduction
+## Choose the Correct gRPC Mode
-### Apache APISIX
+Before configuring a route, identify the client protocol:
-[Apache APISIX](https://apisix.apache.org/) is a dynamic, real-time,
high-performance API gateway that provides load balancing, dynamic upstream,
canary release, service fusion, authentication, observability, and other rich
traffic management features. Apache APISIX not only supports dynamic change and
hot-plugging of plug-ins, but also has a rich library of plug-in resources.
+- **Native gRPC proxying:** the client already speaks gRPC over HTTP/2.
Configure a route and a `grpc` or `grpcs` upstream as documented for APISIX.
+- **gRPC-Web:** a browser uses the gRPC-Web protocol. Use the `grpc-web`
plugin with an appropriate gRPC upstream.
+- **HTTP-to-gRPC transcoding:** an HTTP client sends a request that APISIX
maps to a gRPC service and method. Use `grpc-transcode` and register the
service's `.proto` definition.
-### gRPC
+The `grpc-transcode` plugin does not turn every arbitrary REST API into gRPC
automatically. The configured input must map to the fields and method in the
Protocol Buffers definition, and the current plugin documentation describes
supported request and response behavior.
-[gRPC](https://grpc.io/) is an open source remote procedure call system
initiated by Google. The system is based on HTTP/2 protocol transport, using
Protocol Buffers as the interface description language, and can be run in any
environment. The gRPC service provides pluggable mode support for load
balancing, link tracing, health checking, and authentication, effectively
connecting multiple services between data centers.
+## How `grpc-transcode` Works
-## Plugin Introduction
+For a matching route, APISIX:
-In order to add support for gRPC service proxies, Apache APISIX has released
`grpc-transcode`, a gRPC-based plugin that invokes gRPC services in a RESTful
way.
+1. loads the Protocol Buffers definition referenced by `proto_id`;
+2. maps the HTTP request data to the configured gRPC request message;
+3. calls the configured `service` and `method` on an upstream whose scheme is
`grpc` or `grpcs`;
+4. translates the upstream response into the HTTP response format supported by
the plugin.
-The plugin supports specifying the contents of `.proto` files in Apache APISIX
and implementing proxies for different gRPC services through user-defined gRPC
services.
+This is useful for exposing a controlled HTTP interface to clients that cannot
use native gRPC. It also creates a protocol boundary that must be documented
and tested: HTTP status handling, gRPC status, field encoding, deadlines, and
streaming capabilities are not interchangeable.
-### Integration Principle
+## Prerequisites
-The user specifies the `.proto` content in Apache APISIX, binds the
corresponding proto by the `proto_id` in the `grpc-transcode` plugin, and
configures the Service and Method defined in the `.proto` to implement a proxy
for the gRPC service.
+You need:
-The basic principle is as follows: the user can configure a `grpc-transcode`
plugin in the route, and when the route matches the request, it will forward
the gRPC request to the upstream service.
+- a running APISIX instance and access to its Admin API;
+- a reachable gRPC service;
+- the exact `.proto` definition used by that service;
+- a unary RPC supported by the plugin for this example.
-:::note
-The `grpc-transcode` plugin supports configuration of `proto_id`, `grpc
service name`, `grpc service method`, `grpc deadline`, and `pb_option`. Based
on the configuration, the upstream gRPC service is invoked and the response
obtained from the upstream gRPC service is returned to the client.
-:::
+The following snippets use a minimal `helloworld.Greeter/SayHello` service.
Replace the addresses, credentials, and schema with your own values.
-## How to use
+## Step 1: Register the Protocol Buffers Definition
-### Environment Preparation
+Create a proto resource through the APISIX Admin API. The current resource
path is `/apisix/admin/protos/{id}`.
-Before configuring Apache APISIX, you need to start the gRPC service.
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/protos/1"; \
+ -X PUT \
+ -H "X-API-KEY: $admin_key" \
+ -d '
+{
+ "content": "syntax = \"proto3\";\npackage helloworld;\nservice Greeter {\n
rpc SayHello (HelloRequest) returns (HelloReply) {}\n}\nmessage HelloRequest
{\n string name = 1;\n}\nmessage HelloReply {\n string message = 1;\n}"
+}'
+```
+
+The registered definition must match the package, service, method, and message
types implemented by the upstream. Treat proto changes as an API compatibility
change and promote them through review and testing with the corresponding
service version.
-#### Step 1: Configure the grpc-server-example service
+## Step 2: Create the Transcoding Route
-1. Clone the `grpc-server-example` repository.
+Configure the plugin with the proto resource, fully qualified service name,
and method. Set the upstream scheme to `grpc` for plaintext HTTP/2 inside a
trusted network or `grpcs` when APISIX must use TLS to the upstream.
```shell
-git clone https://github.com/api7/grpc_server_example
+curl "http://127.0.0.1:9180/apisix/admin/routes/grpc-transcode-demo"; \
+ -X PUT \
+ -H "X-API-KEY: $admin_key" \
+ -d '
+{
+ "uri": "/hello",
+ "methods": ["GET"],
+ "plugins": {
+ "grpc-transcode": {
+ "proto_id": "1",
+ "service": "helloworld.Greeter",
+ "method": "SayHello"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "grpc",
+ "nodes": {
+ "127.0.0.1:50051": 1
+ }
+ }
+}'
```
-2. Start grpc-server.
+Restrict methods and request size to what the public API actually supports.
The example embeds an upstream for clarity; production environments may
reference a separately managed upstream object.
-```shell
-cd grpc_server_example
-go run main.go
-```
+## Step 3: Call the HTTP Endpoint
-3. Verify the gRPC service, it is recommended to use `grpcurl` to verify the
availability of the service.
+For the schema above, an HTTP client can provide the `name` field as supported
by the plugin:
```shell
-grpcurl -d '{"name": "zhangsan"}' -plaintext 127.0.0.1:50051
helloworld.Greeter.SayHello
+curl "http://127.0.0.1:9080/hello?name=APISIX";
```
-After correctly starting the gRPC service, executing the above command will
output the following.
+A successful response contains the translated `HelloReply`, for example:
```json
{
- "message": "Hello zhangsan"
+ "message": "Hello APISIX"
}
```
-#### Step 2: Configure Apache APISIX
+The exact encoding and error response depend on the plugin configuration and
APISIX version. Test missing fields, invalid values, upstream timeouts, and
every gRPC status your service can return. Do not infer HTTP semantics solely
from a successful demonstration call.
-1. Add proto
+## Production Considerations
-```shell
-curl http://127.0.0.1:9080/apisix/admin/proto/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "content" : "syntax = \"proto3\";
- package helloworld;
- service Greeter {
- rpc SayHello (HelloRequest) returns (HelloReply) {}
- }
- message HelloRequest {
- string name = 1;
- }
- message HelloReply {
- string message = 1;
- }"
-}'
-```
+### Schema compatibility
-2. In the specified Route, proxy the gRPC service interface.
+Keep the registered proto synchronized with the deployed gRPC service. Follow
Protocol Buffers compatibility rules, avoid reusing field numbers, and test old
clients during a staged rollout.
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/grpctest",
- "plugins": {
- "grpc-transcode": {
- "proto_id": "1",
- "service": "helloworld.Greeter",
- "method": "SayHello"
- }
- },
- "upstream": {
- "scheme": "grpc",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:50051": 1
- }
- }
-}'
-```
+### Deadlines and retries
-Details of the specific code interpretation and supported parameters can be
found below.
+Set bounded timeouts based on the service's latency objective. Retries are
safe only for operations that are idempotent under the application's semantics;
automatically retrying a state-changing RPC can duplicate work.
-| Name | Type | Requirement | Default |
Description |
-|:----------|:-----------------------------|:------|:-------|:---------------------------|
-| proto_id | string/integer | required | N/A | `.proto`
content id |
-| service | string | required | N/A | the grpc
service name |
-| method | string | required | N/A | the method name
of grpc service |
-| deadline | number | optional | 0 | deadline for
grpc in milliseconds |
-| pb_option | array[string(pb_option_def)] | optional | N/A | protobuf
options |
+### TLS and identity
-### Testing Requests
+Use `grpcs` when the network and threat model require upstream TLS, and
configure certificate verification according to the current APISIX upstream TLS
documentation. Client authentication at the HTTP route does not automatically
provide service-to-service identity to the gRPC server.
-Here we will use cURL for testing.
+### Error mapping
-```shell
-curl -i http://127.0.0.1:9080/grpctest\?name=world
-HTTP/1.1 200 OK
-Date: Mon, 27 Dec 2021 06:24:47 GMT
-Content-Type: application/json
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX/2.11.0
-Trailer: grpc-status
-Trailer: grpc-message
-
-{"message":"Hello world"}
-grpc-status: 0
-grpc-message:
-```
+gRPC uses status codes and trailers, while HTTP clients expect HTTP status
codes and bodies. Define which translated errors form part of the public API
contract and verify them with integration tests. Preserve enough structured
detail for clients without exposing internal stack traces.
-The feedback from the code shows that the request was successfully proxied to
the back-end gRPC service.
+### Streaming
-### Disabling the plugin
+Do not assume an HTTP transcoding route supports every client-, server-, or
bidirectional-streaming pattern. Check the current plugin limitations. Native
gRPC proxying may be the appropriate design when streaming is required.
-If you are done using the `grpc-transcode` plugin on the route, simply remove
the plugin-related configuration from the route configuration to turn off the
`grpc-transcode` plugin on the route.
+### Observability
-Thanks to the Apache APISIX plugin hot-loading mode, there is no need to
restart Apache APISIX to turn it on and off.
+Capture route latency, upstream latency, gRPC status, HTTP status, and
timeouts with bounded labels. Propagate trace context when supported, and
redact credentials and sensitive request fields from logs.
-```shell
-# Disable the plugin
-curl http://127.0.0.1:9080/apisix/admin/routes/111 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/grpctest",
- "plugins": {},
- "upstream": {
- "scheme": "grpc",
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:50051": 1
- }
- }
-}'
-```
+## Frequently Asked Questions
+
+### Is `grpc-transcode` required to proxy native gRPC?
+
+No. It is for translating an HTTP request into a gRPC call. A client that
already uses native gRPC can be proxied with an appropriate gRPC route and
upstream without HTTP-to-gRPC transcoding.
+
+### Is this the same as gRPC-Web?
+
+No. gRPC-Web is a browser-oriented protocol handled by the `grpc-web` plugin.
`grpc-transcode` exposes an HTTP-style interface mapped through a proto
definition.
+
+### Can APISIX infer the service and method from the proto?
+
+The route explicitly configures `proto_id`, `service`, and `method`. This
keeps the exposed HTTP route tied to a specific RPC rather than exposing every
method in a schema by default.
+
+### Where is the current field reference?
+
+Use the official [`grpc-transcode` plugin
documentation](https://apisix.apache.org/docs/apisix/plugins/grpc-transcode/)
for the supported fields, request mappings, response options, and
version-specific limitations.
-## Summary
+## Conclusion
-This article provides a step-by-step guide to using the `grpc-transcode`
plugin to proxy requests to a back-end gRPC service via RESTful. By using this
plugin, Apache APISIX can be configured to proxy to the gRPC service only.
+The APISIX `grpc-transcode` plugin is a protocol adapter for a defined
HTTP-to-gRPC route. Register the exact proto, bind one service and method,
configure a gRPC upstream, and test schema, deadline, error, and security
behavior as part of the public API contract.
-For more descriptions and a complete configuration list of the grpc-transcode
plugin, please refer to the [official
documentation](https://apisix.apache.org/docs/apisix/next/plugins/grpc-transcode/).
+Use native gRPC proxying or gRPC-Web when those protocols match the client
instead of adding an unnecessary transcoding layer.
diff --git a/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md
b/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md
index 10a3ae2db0c..d6630bdec61 100644
--- a/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md
+++ b/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md
@@ -1,101 +1,167 @@
---
-title: "Event-Driven APIs with Webhook and API Gateway"
+title: "Using an API Gateway for Secure Webhook Delivery"
authors:
- name: Bobur Umurzokov
title: Author
url: https://github.com/Boburmirzo
image_url: https://avatars.githubusercontent.com/u/14247607
-keywords:
-- API Gateway
-- Apache APISIX
-- API
-- Architecture
-- Use-cases
-- Webhook
-- Event-driven
-description: "Learn how Apache APISIX can secure, route, and manage webhook
APIs and event-driven traffic with gateway policies and plugins."
+keywords:
+ - API Gateway
+ - Apache APISIX
+ - Webhook API
+ - Event-Driven Architecture
+ - Webhook Security
+description: "Learn where an API gateway fits in a webhook architecture, from
subscription and inbound security to retries, idempotency, and observability."
tags: [Ecosystem]
image: https://static.apiseven.com/2022/11/07/6368d30abf672.png
---
-> There are many ways and technology options to consider when implementing an
event-driven API. For example, we explored how to [build event-driven APIs
using these 3 well-known
patterns](https://dev.to/apisix/building-event-driven-api-services-using-cqrs-api-gateway-and-serverless-af4):
[CQRS](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs),
[API Gateway](https://apisix.apache.org/docs/apisix/terminology/api-gateway/)
and [Serverless](https://learn.microsoft.com/en-u [...]
+Webhooks let an event producer notify a consumer by making an HTTP request to
a callback URL. An API gateway can protect and route the HTTP-facing parts of
that design, but it does not by itself provide durable event delivery, callback
validation, retry scheduling, or idempotent processing. Those responsibilities
need to be designed explicitly.
<!--truncate-->
-## Need for a webhook
+## Why Use Webhooks Instead of Polling?
-Consuming applications expect to be informed of any change of state on a
specific record or records.
+Polling asks an API repeatedly whether a resource has changed. It is
straightforward, but frequent polls may return no new data and create
unnecessary load. A webhook reverses the interaction: the producer sends an
HTTP request when a relevant event occurs.
-Examples:
+Common examples include:
-- Updating or adding customers in a CRM system triggers an event.
-- Currency exchange rates from a foreign exchange application informs users
about currency change.
-- New post on a user's blog notifies subscribers.
-- New order creation on an online shopping application informs another service
in the system.
-- An orchestrator service wants to be notified when Service A completes a task
and when to handover the task to Service B in a data ingestion pipeline and so
on.
+- notifying a fulfillment service when an order is paid;
+- updating a CRM integration after a customer record changes;
+- telling a subscriber that a long-running job completed;
+- triggering a deployment or automation workflow after a repository event.
-The majority of APIs only support these types of requirements by having the
consuming application constantly poll for changes. This means that the
consuming application has to make frequent API calls to find out any changes of
state in the desired resource. This is highly inefficient, and calls may result
in empty payloads when there haven't been any updates. Also, what if the called
HTTP API accepts our HTTP request but takes a long time to handle it, this
could affect the user experien [...]
+Webhooks are appropriate when consumers can expose a reachable callback and
tolerate asynchronous, at-least-once delivery. Polling or an event-streaming
system may be a better fit when callbacks are not reachable, consumers need
replay over a long history, or very high event volume requires a different
delivery model.
-Instead of having to constantly poll for changes, create a subscription
endpoint against a specific resource so consuming applications can register
their interest to be informed on any change of state (an event) by providing a
call-back endpoint. At this point, it becomes the API's responsibility to send
back any change of state by posting the updates to the registered endpoint.
+## The Components of a Webhook System
-
+A production design usually includes more than one HTTP endpoint:
-## What’s Webhook?
+1. **Subscription API:** registers the events and callback URL a consumer
wants to receive.
+2. **Event producer:** records a business event after the relevant state
change succeeds.
+3. **Delivery worker:** creates signed webhook requests, applies retry policy,
and records delivery state.
+4. **Consumer endpoint:** authenticates the request, deduplicates it,
acknowledges receipt, and processes the event.
+5. **API gateway:** can route and protect the subscription API, delivery API,
or consumer endpoint, depending on which side of the integration you operate.
-A [webhook](https://en.wikipedia.org/wiki/Webhook) is a software architecture
approach that allows applications and services to submit a web-based
notification to other applications whenever a specific event occurs. The
application provides a way for users to register or connect API calls to
certain events under specific conditions, such as when a new user, account, or
order is created or an order ships out of a warehouse.
+The gateway is an HTTP policy and traffic component. A durable queue, outbox,
or delivery store is normally responsible for surviving process restarts and
retrying events without losing them.
-Webhooks are generally used to notify clients of events, in real-time, as they
occur. They normally take the form of HTTP POST endpoints that can be requested
with a JSON body and it is fully managed by an event consumer. An event
producer, such as an API server, can send event notifications to a webhook when
something interesting happens.
+## Where an API Gateway Fits
-## Webhook and API Gateway in Event-Driven Architecture
+### Protecting the subscription API
-Leveraging Webhook and API Gateway enables you to build an event-driven API
that can be decoupled from your main application code. Enabling you to call
external systems that have subscribed via webhooks in complete isolation from
your application code.
+A gateway can authenticate subscribers, limit registration traffic, enforce
request-size constraints, and route subscription requests to the application
that owns subscriber data.
-
+The application must still validate callback URLs. In particular, prevent
server-side request forgery by rejecting unsupported schemes, credentials in
URLs, local and link-local addresses, and destinations that resolve to
protected networks. Revalidate DNS resolution at delivery time when the threat
model requires it, and control redirects rather than following them blindly.
-As you can see in the preceding architectural diagram, there are two main
flows.
+### Receiving inbound webhooks
-### Subscription process
+When your system consumes webhooks, the gateway can terminate TLS, restrict
request size, apply source controls where appropriate, and route events to the
correct receiver. Authentication depends on the provider: it may use an HTTP
signature, a shared secret, mTLS, an OAuth token, or another documented
mechanism.
-In the first flow on the left, API Consumers can subscribe to the API by
registering a Webhook URL as the callback. A consuming application subscribing
for changes in a resource by making a POST call (with the call-back URL in the
body) to a resource subscription API endpoint (for example,
`/{resource}/subscribe`) exposed in an API gateway. Once the API gateway
receives the call, it routes the request to the subscription service, which
then adds the subscriber details to a database.
+Do not assume that IP allowlists alone authenticate a sender, or that every
provider signs requests the same way. Signature verification often depends on
the exact raw request body and provider-specific timestamp rules. If a gateway
plugin transforms the body before verification, the signature check can fail or
verify the wrong representation.
-
+### Sending outbound webhooks
-It is also possible to unsubscribe from the API. In this scenario, API
Gateway’s tasks first identify unknown messages so be sure that the request is
always authenticated and credentials are valid, it returns a `2xx response`
immediately as an acknowledgment or if the request cannot be authenticated or
there is an error getting the payload into a staging system, an error is
returned. Then it is also passing the request to the responsible service based
on the path provided by the consumer.
+An outbound delivery service can use a gateway as a controlled egress point
for TLS policy, destination policy, telemetry, and network routing. The gateway
does not automatically decide which events to send, persist them, or retry them
safely. Keep those responsibilities in the producer, outbox, queue, and
delivery worker.
-### Callback process
+## Subscription Flow
-In the second flow on the right, we are delivering events to API consumers
asynchronously through the call-back component and the API Gateway. An event
listener service queries the database as subscribers are matched against
particular processed events. The event listener service then creates call-back
commands and publishes them in an Event Hub so a call-back service can execute
all API calls (and retries if necessary) via the API gateway.
+A safe subscription flow can follow these steps:
-
+1. The consumer authenticates to the subscription API.
+2. The application authorizes the requested event types and tenant.
+3. The callback URL passes syntax, scheme, destination, and ownership checks.
+4. The producer stores a subscription identifier and a protected signing
secret or public-key association.
+5. If ownership verification is required, the system sends a challenge and
activates the subscription only after the correct response.
+6. The API returns the subscription state without exposing secret material.
-There, API Gateway plays not only a role of a reverse proxy but can convert
internal calls from one format to another. For example, the call-back service
is using another [AMQP](https://www.amqp.org/) (Advanced Message Queuing
Protocol) messaging protocol but the API should make a REST call to the
consumer’s callback endpoint, in this gateway an API Gateway such as [Apache
APISIX](https://apisix.apache.org/) can help. It can receive a REST request,
then transform it to the desired format [...]
+Rate limits at the gateway can reduce abuse, but business rules such as which
tenant may subscribe to which account belong in the subscription service.
-Also, it comes with other concerns like securing it with certificates and
preventing [DDoS
attacks](https://en.wikipedia.org/wiki/Denial-of-service_attack). And it
enables a monitoring feature for your webhook to be able to see what is going
on with the webhook, you know like what is wrong with the configuration on the
API provider side.
+## Delivery Flow
-One of the most efficient ways to handle the **webhook processing part** of
the above architecture by using API Gateway of your choice and an event-driven
serverless function.
+When the source transaction commits, record the event in a durable outbox or
publish it to a durable broker. A delivery worker then:
-## Summary
+1. assigns a stable event or delivery identifier;
+2. serializes the documented payload;
+3. creates the authentication signature or credential;
+4. sends the request with a bounded connection and response timeout;
+5. records the response and schedules a retry when the policy permits;
+6. moves repeatedly failing deliveries to a bounded failure state for
investigation or replay.
-As we understood throughout the post, Webhook tries to decouple the concerns
like a message acknowledgment and the processing messages in the API and no
synchronous business logic is performed. However, the above architectural
example we discussed can be a complicated pattern to implement given that it
has many moving parts and the API are not aware of a consuming application
endpoint is up and running but that can be improved. In addition to this,
Webhooks force the event consumer to es [...]
+Avoid sending the callback synchronously inside the source transaction. A slow
or unavailable consumer should not hold open the user-facing request that
produced the event.
-### Related resources
+## Security Controls
-➔ [Building event-driven API services using CQRS, API Gateway and
Serverless](https://dev.to/apisix/building-event-driven-api-services-using-cqrs-api-gateway-and-serverless-af4).
+### Authenticate every delivery
-➔ [API
Gateway](https://apisix.apache.org/docs/apisix/terminology/api-gateway/).
+Use the mechanism documented by the provider or define a clear signing scheme
for your own webhooks. A typical signature design includes the raw body, a
timestamp, and a delivery identifier, and uses a current secret or private key.
The consumer should compare signatures in constant time and reject timestamps
outside a configured tolerance.
-### Recommended content 💁
+### Prevent replay
-➔ Watch Video Tutorial:
+A timestamp limits how long a captured request remains useful. Store recently
accepted delivery identifiers so a repeated valid request is not processed
twice. The retention period should cover the sender's maximum retry window.
-- [Getting Started with Apache APISIX](https://youtu.be/dUOjJkb61so).
-
-- [APIs security with Apache APISIX](https://youtu.be/hMFjhwLMtQ8).
+### Protect secrets and logs
-- [Implementing resilient applications with API Gateway (Circuit
breaker)](https://youtu.be/aWzo0ysH__c).
+Store webhook secrets in protected secret storage, limit access, and support
rotation with a short, auditable overlap. Redact authorization headers,
signatures, tokens, and sensitive payload fields from gateway and application
logs.
-➔ Read the blog posts:
+### Treat callback destinations as untrusted input
-- [Implementing resilient applications with API Gateway (Health
Check)](https://dev.to/apisix/implementing-resilient-applications-with-api-gateway-health-check-338c).
+Callback URLs can be used to probe internal services or cloud metadata
endpoints. Apply destination policy before each delivery, restrict ports and
schemes, use controlled egress, and set conservative timeouts and response-size
limits.
-- [10 most common use cases of an API
Gateway](https://apisix.apache.org/blog/2022/10/27/ten-use-cases-api-gateway/).
+## Reliability and Idempotency
+
+Webhook delivery is commonly at least once: a consumer can process an event
and then fail before its acknowledgement reaches the sender. The sender sees a
timeout and retries, so the consumer receives a duplicate.
+
+Design the handler to be idempotent:
+
+- use the stable event identifier as a deduplication key;
+- make state transitions conditional on the current state;
+- protect deduplication records with an atomic insert or equivalent constraint;
+- retain records for at least the documented retry period.
+
+Retry only operations and status classes allowed by your contract. Use
exponential backoff with jitter, a maximum attempt count, and a maximum
delivery age. Honor `Retry-After` when the receiver uses it and your policy
permits. Do not retry permanent authentication, validation, or
destination-policy failures indefinitely.
+
+Consumers should acknowledge only after the event has been durably accepted.
If processing is slow, enqueue the event and return a success response after
that durable handoff rather than keeping the HTTP request open.
+
+## Observability
+
+Track delivery outcomes without exposing sensitive payloads. Useful dimensions
include:
+
+- subscription and event type;
+- attempt count and delivery age;
+- destination class or tenant, with cardinality controls;
+- response status, timeout, and policy rejection;
+- queue delay and failure-state volume.
+
+Propagate a correlation identifier from the event record through the gateway
and delivery worker. Alert on sustained failure rates and growing queue age,
not on a single transient retry.
+
+## Using Apache APISIX
+
+[Apache APISIX](https://apisix.apache.org/) can route webhook HTTP endpoints
and apply plugins for authentication, traffic control, observability, request
restrictions, and other gateway policies. Select and test policies for the
exact inbound or outbound flow; not every responsibility described above
belongs in APISIX.
+
+For example, APISIX can expose `/webhooks/{provider}` routes to receiver
services and apply per-route size limits and telemetry. The receiver should
still perform provider-specific signature and replay checks unless a verified
plugin implements that exact scheme. Likewise, a durable event store and
delivery worker should own outbound retries and idempotency.
+
+Review available [APISIX
plugins](https://apisix.apache.org/docs/apisix/plugins/) and keep custom
plugins small, bounded, and outside the durable workflow state machine.
+
+## Frequently Asked Questions
+
+### Is a webhook the same as an event stream?
+
+No. A webhook pushes an HTTP request to a callback. An event stream or broker
usually provides different retention, ordering, replay, and consumer
coordination capabilities. They can be used together: a broker stores events
while a worker delivers selected events as webhooks.
+
+### Can an API gateway guarantee webhook delivery?
+
+No. A gateway can route and observe an HTTP attempt, but durable delivery
requires persisted event state, retry scheduling, and a defined failure/replay
process.
+
+### Should a webhook return `200` immediately?
+
+Return a documented success status only after the event is authenticated and
durably accepted. Long processing should usually happen asynchronously.
Returning success before durable acceptance can lose events; waiting for all
business processing can cause unnecessary retries.
+
+### Are webhook retries safe?
+
+Only when the sender uses bounded retry rules and the consumer processes
repeated event identifiers idempotently. Network timeouts make duplicate
delivery normal, not exceptional.
+
+## Conclusion
+
+An API gateway is useful at the HTTP boundary of a webhook system: it can
secure, limit, observe, and route subscription and delivery traffic. Durable
events, callback validation, authentication semantics, retries, and idempotent
processing require application and messaging components with explicit ownership.
+
+Design those responsibilities first, then apply gateway policies that
reinforce the design without hiding or duplicating the delivery state machine.
diff --git
a/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
b/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
index 6d053708ff6..b5a39504855 100644
--- a/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
+++ b/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
@@ -1,5 +1,5 @@
---
-title: Why Do Microservices Need an API Gateway
+title: Why Microservices Use an API Gateway
authors:
- name: API7.ai
title: Author
@@ -8,98 +8,145 @@ authors:
keywords:
- Apache APISIX
- Microservices
- - Alternatives to Kong
-description: Let's learn the importance of API gateway in the microservices
architecture, and compare common API gateways.
+ - Microservices API Gateway
+ - API Gateway Architecture
+description: Learn when microservices need an API gateway, which
responsibilities belong at the gateway, and when a simpler alternative is
enough.
tags: [Ecosystem]
image:
https://static.apiseven.com/uploads/2023/02/16/CHqaC3Xw_Ecosystem%20%E6%A8%A1%E6%9D%BF1.png
---
->The microservices architecture has been widely adopted by many companies. As
the data and API quantity of microservices increases, it is crucial to choose
an excellent API gateway for high-traffic governance: APISIX.
+An API gateway can give clients one entry point to a set of microservices and
apply shared traffic policies before requests reach those services. It is
useful in many microservice systems, but it is not a requirement for every
architecture. The decision depends on client exposure, traffic policies, team
ownership, and operational complexity.
+
<!--truncate-->
-## What Are Microservices
+## What Is a Microservice Architecture?
+
+A microservice architecture divides an application into independently
deployable services organized around business capabilities. Services commonly
communicate through synchronous APIs, asynchronous messages, or both.
+
+This approach can let teams release and scale parts of a system independently.
It also introduces distributed-system concerns: network failures, service
discovery, end-to-end observability, identity propagation, versioning, and
consistency across service boundaries. A gateway addresses some edge-traffic
concerns, but it does not solve every microservice challenge.
+
+## What Does an API Gateway Do?
+
+An API gateway receives client traffic, matches it to a route, and proxies it
to an upstream service. Depending on the gateway and its configuration, it can
also apply policies such as:
+
+- client authentication and coarse-grained authorization;
+- rate limits, request-size limits, and other traffic controls;
+- TLS termination and certificate management;
+- request or response transformation;
+- load balancing and health-based routing;
+- metrics, access logs, and tracing integration;
+- canary or weighted routing between service versions.
+
+The gateway is part of the request path. Its availability, capacity,
configuration security, and failure behavior therefore need the same
engineering attention as other production infrastructure.
+
+## Why Put a Gateway in Front of Microservices?
+
+### Give external clients a stable entry point
+
+Without a gateway or another edge proxy, clients may need to know the location
and interface of each exposed service. A gateway can keep internal service
addresses private and present stable public routes while services move or scale
behind it.
+
+This indirection helps, but it is not a substitute for API versioning and
compatibility. A gateway can route versions; service owners still need to
design and deprecate interfaces deliberately.
+
+### Apply shared edge policies consistently
+
+Authentication, traffic limits, request validation, and telemetry often need a
consistent enforcement point. Implementing the same edge policy independently
in every service can produce drift and repeated maintenance.
+
+Centralization should be selective. Business authorization rules usually
require domain context and often belong in the service as well. A gateway check
does not remove the need for service-to-service identity, authorization, or
input validation behind the gateway.
+
+### Protect upstream capacity
+
+Rate limits, concurrency controls, timeouts, and circuit-breaking policies can
reject or contain some harmful traffic before it consumes service capacity.
These policies must be based on measured service limits and realistic failure
modes. A rate limit alone cannot guarantee availability, and an incorrectly
configured retry policy can amplify an outage.
+
+### Improve traffic visibility
+
+A gateway can generate consistent access logs and traffic metrics for requests
that pass through it. Distributed traces can then connect gateway spans with
downstream services when trace context is propagated correctly.
+
+Gateway telemetry is only one view. It does not reveal internal asynchronous
work or service-to-service calls that bypass the gateway, so services and
message infrastructure still need their own instrumentation.
-Microservice architecture, usually referred to as
[microservices](https://api7.ai/blog/what-are-microservices), is a type of
architecture used to develop applications. With microservices, large
applications can be broken down into multiple independent components, each with
its own responsibilities. When processing a user request, an application based
on microservices may call many internal microservices to generate its response
jointly. Microservices are a result of internet development, [...]
+### Change routing without changing clients
-Overall, the architecture of systems has roughly evolved from monolithic
architecture to SOA architecture to microservice architecture. The specific
progression and pros/cons of each architecture are outlined in the table below.
+Gateways can support weighted traffic splitting, header-based routing, and
controlled migration between upstream versions. This is useful for canary
releases and service decomposition, provided that the configuration is
reviewed, tested, and easy to roll back.
-| Architecture Type | Description
|
Advantages
| Disadvantages
|
-|----|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
-| Monolithic Application Architecture | Pack all functional code into a
single service. | 1. Simple architecture with low project development and
maintenance costs.
| Coupling all modules together is beneficial for developing and maintaining
small projects, but it can create issues for large projects, including <br/> 1.
The modules in the pr [...]
-| [SOA
Architecture](https://en.wikipedia.org/wiki/Service-oriented_architecture)
| The term stands for "service-oriented architecture," which typically
involves multiple services. <br/>A service typically exists independently in an
operating system process, and communication between services is achieved
through dependencies or communication mechanisms, <br/> Ultimately, it provides
a series of functions.
[...]
-| Microservice Architecture | Microservices are the
sublimation of SOA. One of the key emphases of the microservices architecture
is "the need to thoroughly componentize and serviceize business", <br/>The
original single business system will be split into multiple parts that can be
developed, designed, and deployed independently.<br/>These parts will run as
small, independent applications. Each application will collaborate and
communicate with the others to achieve integ [...]
+## When You May Not Need an API Gateway
-Therefore, microservices are an inevitable result of Internet development, and
the system architecture of many traditional companies is gradually becoming
microservice-oriented.
+A gateway adds another component and another policy layer. A simpler option
may be sufficient when:
-However, with Internet business development, the number of APIs is also
increasing dramatically, and gateways for unified API management will also face
challenges. Choosing a more robust API gateway can effectively enhance the
system's capabilities in monitoring, disaster recovery, authentication, and
rate limiting.
+- the system has one internal client and only a few services;
+- no API is exposed outside a trusted network boundary;
+- an existing ingress proxy already provides the required routing and TLS
features;
+- service-mesh ingress or a cloud load balancer covers the current use case;
+- the team cannot yet operate the gateway reliably.
-## What Is an API Gateway?
+Direct client-to-service access, a reverse proxy, an ingress controller, and a
gateway are design choices with overlapping capabilities. Start from concrete
requirements rather than adding a gateway because the architecture is called
“microservices.”
-API gateway provides a unified interface for interactions between clients and
service systems and serves as a central point for managing requests and
responses. Choosing a suitable API gateway can simplify development and improve
system operation and management efficiency.
+## Gateway Responsibilities vs Service Responsibilities
-In a microservices architecture, an API gateway serves as a solution for
system design by integrating various microservices from different modules and
coordinating services in a unified manner.
+Clear ownership prevents a gateway from becoming a monolithic business-logic
layer.
-As a system access aspect, the API gateway provides a unified entry point for
clients, hides the implementation details of the system architecture, and makes
microservices more user-friendly. It also integrates some common features such
as [authentication](https://api7.ai/blog/api-gateway-authentication), [rate
limiting](https://api7.ai/blog/rate-limiting-in-api-management), and circuit
breaking to avoid individual development of each microservice, improve
efficiency, and standardize the [...]
+| Concern | Typical gateway role | Typical service role |
+| --- | --- | --- |
+| Authentication | Validate supported client credentials or tokens | Enforce
identity requirements for internal calls where needed |
+| Authorization | Apply route- or consumer-level policy | Enforce resource-
and domain-level permissions |
+| Rate limiting | Protect shared entry points and upstream capacity | Apply
business quotas or workload-specific limits |
+| Validation | Enforce basic protocol, size, or schema constraints | Validate
domain rules and state transitions |
+| Observability | Record edge traffic and propagate trace context | Instrument
internal work and business outcomes |
+| Composition | Perform limited protocol or payload adaptation | Own workflows
and business orchestration |
-## Why Do Microservices Need an API Gateway?
+Avoid putting long-running orchestration or domain decisions in gateway
plugins merely to centralize them. That increases coupling and makes the
traffic layer harder to operate and test.
-
+## Common Architecture Risks
-As shown in the above diagram, the API gateway serves as an intermediate layer
between the client and microservices. It can provide microservices to the
outside world at a unified address and route the traffic to the correct service
nodes within the internal cluster based on appropriate rules.
+### A single unmanaged gateway failure domain
-Without an API gateway, the inlets and outlets of the traffic are not unified,
and the client needs to know the access information of all services. The
significance of microservices will not exist. Therefore, a microservices
gateway is necessary for a microservice architecture. Additionally, the API
gateway plays a vital role in system observability, identity authentication,
stability, and [service
discovery](https://api7.ai/blog/what-is-service-discovery-in-microservices).
+Deploy enough data-plane capacity across appropriate failure domains, define
health checks, and test behavior when the control plane or configuration store
is unavailable. “Using a gateway” does not itself create high availability.
-### Challenges Faced by Microservices
+### One policy for every service
-The microservices gateway should first have API routing capabilities. As the
number of microservices increases, so does the number of APIs. The gateway can
also be used as a traffic filter in specific scenarios to provide certain
optional features. Therefore, higher demands are placed on the microservices
API gateway, such as:
+Different upstreams have different latency, capacity, data sensitivity, and
client behavior. Use route- or consumer-specific controls where the risk
justifies them, and preserve an auditable default policy.
-- Observability: In the past, troubleshooting in monolithic applications was
often done by checking logs for error messages and exception stacks. However,
in a microservices architecture with many services, problem diagnosis becomes
very difficult. Therefore, how to monitor the operation of microservices and
provide rapid alarms when anomalies occur poses a great challenge to developers.
-- Authentication and Authorization: In a microservices architecture, an
application is divided into several micro-applications, which need to
authenticate access and be aware of the current user and their permissions.The
[authentication](https://api7.ai/blog/understanding-microservices-authentication-services)
method in monolithic application architecture is unsuitable, especially when
access is not only from a browser but also from other service calls. In a
microservices architecture, v [...]
-- System stability: If the number of requests exceeds the processing capacity
of a microservice, it may overwhelm the service, even causing a cascading
effect that affects the system's overall stability.
-- Service discovery: The decentralized management of microservices also
presents challenges for implementing load balancing.
+### Treating the gateway as the only security boundary
-### Solutions
+Protect administrative APIs and configuration stores, restrict network access,
rotate secrets, and secure service-to-service communication. Services should
not blindly trust client-controlled identity headers; the architecture must
ensure those headers are removed or set only by a trusted component.
-API gateway, as the intermediate bridge between the client and the server,
provides a unified management mechanism for the microservices system. In
addition to basic functions such as request distribution, API management, and
conditional routing, it also includes identity authentication, monitoring and
alarm, tracing analysis, load balancing, rate limiting, isolation, and circuit
breaking.
+### Unbounded gateway customization
-**Identity authentication**: The following diagram illustrates how
microservices are united with an API gateway for identity authentication, where
all requests go through the gateway, effectively hiding the microservices.
+Plugins run in a critical traffic component. Review custom code, constrain
network and secret access, test failure behavior, and keep expensive or
blocking work out of the request path.
-
+## Using Apache APISIX with Microservices
-**Monitoring and Alerting/Tracing Analysis**:
+[Apache APISIX](https://apisix.apache.org/) is an open-source API gateway that
provides dynamic routing and a plugin model for traffic management,
authentication, observability, and protocol handling. It can run as a gateway
for services deployed on virtual machines, containers, or Kubernetes, depending
on the selected deployment architecture.
-As the intermediary between the client and server, the API gateway is an
excellent carrier for monitoring microservices.
+A practical evaluation should verify:
-The primary responsibility of the API gateway's monitoring function is to
detect connection anomalies between the gateway and the backend servers in a
timely manner. Users can view log information, monitoring information, tracing,
etc. on the monitoring platform for the API. Furthermore, any anomalies that
arise on the host will be automatically reported to the control panel. Specific
gateways can issue dual alerts to both the client and server.
+1. how routes and upstreams are configured and promoted between environments;
+2. which authentication and authorization model protects each API;
+3. how APISIX discovers or receives updates about service endpoints;
+4. what telemetry is exported and how sensitive data is handled;
+5. how the data plane behaves during upstream, network, and control-plane
failures;
+6. how upgrades, backups, rollbacks, and incident response are performed.
-
+Start with the [APISIX getting-started
guide](https://apisix.apache.org/docs/apisix/getting-started/) and evaluate
only the [plugins](https://apisix.apache.org/docs/apisix/plugins/) required by
the workload. Fewer well-tested policies are safer than enabling features
without a clear owner.
-**Rate limiting, isolation, and circuit breaking**:
+## Frequently Asked Questions
-As the scale of internet businesses continues to increase, so does the
concurrency of systems. Multiple services are often called by each other, and a
core link may call up to ten services. If the RT (response time) of a certain
service rises sharply and upstream services continue to request, a vicious
cycle will occur. The more upstream waiting for results, the more upstream
services will be blocked, and the entire process will eventually become
unusable, leading to a service avalanche.
+### Do all microservices need to pass through one gateway?
-Therefore, it is necessary to regulate and manage the incoming traffic. The
following diagram shows how microservice systems combine API gateways to
perform rate limiting, isolation, and circuit breaking.
+No. External or north-south traffic commonly enters through a gateway, while
internal service-to-service traffic may use direct discovery, a service mesh,
or another controlled path. The topology should reflect trust boundaries and
operating requirements.
-
+### Is an API gateway the same as a service mesh?
-### Selection of Mainstream Gateways
+No. Their capabilities can overlap, but a gateway usually focuses on
client-to-service entry traffic and API policies. A service mesh generally
focuses on communication between workloads. Some systems use both; smaller
systems may need only one.
-Many open-source gateway implementations are available in microservices,
including NGINX, Kong, Apache APISIX, and Envoy. For the Java technology stack,
there are options such as Netflix Zuul, Spring Cloud Gateway, Soul, etc. But
you may wonder, "[Why would you choose Apache APISIX instead of NGINX and
Kong](https://api7.ai/blog/why-choose-apisix-instead-of-nginx-or-kong)?"
+### Does a gateway remove authentication code from every service?
-Here's a brief comparison.
+It can centralize supported client authentication, but services may still need
authorization and identity checks, especially for internal calls and
resource-level permissions. Design explicit trust and identity propagation
rules.
-| Gateway | Painpoints
| Advantages
|
-|---|------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [NGINX](https://www.nginx.com/) | 1. Reloading is required for changes to
take effect in the configuration, which can't keep pace with the progress of
cloud-native technologies.
| 1. old-style applications;<br/>
2. Stable, reliable, and time-tested; <br/> 3. High Performance
|
-| [Apache APISIX](https://apisix.apache.org/) | 1. The documentation is not
rich or clear enough and needs improvement.
| 1.
Apache Foundation Top-Level Project;<br/> 2. The technical architecture is more
in line with cloud-native principles;<br/> 3. Excellent performance;<br/> 4.
Rich ecosystem;<br/> 5. In addition to supporting Lua development plugins, it
also supports languag [...]
-| [Kong](https://konghq.com/) | 1. The default use of PostgreSQL or Cassandra
databases makes the entire architecture very bloated and can bring about high
availability issues;<br/> 2. The routing uses a traversal search algorithm,
which can lead to a significant decrease in performance when there are more
than thousands of routes in the gateway;<br/> 3. Some important features
require payment; | 1. The pioneer of open-source API gateways with a large user
base;<br/> 2. Performance meets [...]
-| [Envoy](https://envoy.com/) | 1. It is developed in C++, which makes it
difficult for secondary development;<br/> 2. In addition to developing filters
with C++, it also supports WASM and Lua.
| 1. The CNCF graduated project is more suitable for
service mesh scenarios and supports the deployment of multi-language
architectures;
|
-| [Spring Cloud
Gateway](https://cloud.spring.io/spring-cloud-gateway/reference/html/) |
1. Although the Spring community is mature, there is a lack of resources for
Gateway.
| 1. The gateway provides a wealth of out-of-the-box
features, which can be used through SpringBoot configuration or hand-coded
calls; <br/> 2. Spring framework is highly extensible with strong scalability,
easy [...]
+### Can an API gateway orchestrate multiple microservices?
-## Summary
+Some gateways can transform or chain requests through plugins, but business
workflows are usually easier to test and own in an application or orchestration
service. Keep gateway composition limited and measurable.
-As the internet world continues to develop, enterprises rapidly evolve,
leading to constant changes in system architecture. The microservices
architecture has been widely adopted by many companies.
+## Conclusion
-As the data and API quantity of microservices increases, it is crucial to
choose an excellent API gateway for high-traffic governance.
+Microservices do not automatically require an API gateway. A gateway is
valuable when a system needs a stable entry point, consistent edge policies,
upstream protection, traffic observability, or controlled routing across many
services. It is unnecessary overhead when simpler infrastructure already
satisfies those requirements.
-This article compares common API gateways, highlighting their respective
advantages and disadvantages. Suppose you are in the process of selecting an
API gateway technology, encountering performance issues in your microservice
system, or looking to build an efficient and stable microservice system. In
that case, this article aims to provide you with some helpful insights.
+Define the boundary, assign each policy to the gateway or service
deliberately, and test the complete failure model before making the gateway a
critical production dependency.
diff --git a/blog/en/blog/2023/10/07/apisix-gitops-adc.md
b/blog/en/blog/2023/10/07/apisix-gitops-adc.md
index 4472d8684d3..de9bd943084 100644
--- a/blog/en/blog/2023/10/07/apisix-gitops-adc.md
+++ b/blog/en/blog/2023/10/07/apisix-gitops-adc.md
@@ -1,5 +1,5 @@
---
-title: "Embracing GitOps: APISIX's New Feature for Declarative Configuration"
+title: "Manage APISIX Declarative Configuration with ADC and GitOps"
authors:
- name: Jintao Zhang
title: Author
@@ -13,312 +13,214 @@ keywords:
- Open Source
- API Gateway
- Apache APISIX
-description: APISIX strengthens its integration with modern development and
operational workflows by introducing the declarative configuration tool, ADC.
+ - GitOps
+ - ADC
+ - Declarative Configuration
+description: "Use ADC lint, diff, sync, dump, and OpenAPI conversion commands
in a reviewed GitOps workflow for Apache APISIX configuration."
tags: [Community]
image: https://static.apiseven.com/2022/10/19/634f6677742a1.png
---
-APISIX strengthens its integration with modern development and operational
workflows by introducing the declarative configuration tool, ADC.
+ADC is a command-line tool for managing API gateway configuration
declaratively. With Apache APISIX, teams can keep intended routes, services,
upstreams, and other supported resources in version control, review changes,
compare them with a target gateway, and synchronize an approved file.
+
<!--truncate-->
-With the widespread adoption of cloud-native and microservices, the API
gateway has emerged as a critical component for connecting and managing various
microservices. However, as the number of services continues to grow and changes
occur more frequently, the traditional imperative configuration has become
increasingly challenging to manage and maintain. GitOps, on the other hand, is
an operational model that leverages version control systems and automated
workflows. By supporting declara [...]
+ADC helps automate a workflow, but installing a CLI does not make the workflow
GitOps by itself. A production design still needs review, protected
credentials, environment promotion, drift policy, verification, and rollback
procedures.
+
+## What Declarative Gateway Configuration Changes
-To enhance developing efficiency and operational reliability, APISIX has
introduced a new tool that supports GitOps in a declarative manner. By
embracing the declarative nature of GitOps, APISIX strengthens its integration
with modern development and operational workflows. This integration enables
smoother collaboration between developers and operations teams, promoting
efficient and reliable management of the APISIX platform.
+An imperative workflow sends a sequence of create, update, and delete
requests. The history may show what commands ran, but it can be difficult to
see the intended final state.
-## Why Does APISIX Support GitOps Declarative Configuration
+A declarative workflow stores the desired state in a file and asks a tool to
compare or reconcile that state with a target system. This can improve:
-Although APISIX offers a stand-alone mode that allows configuration through
YAML files, it lacks seamless integration with related ecosystems such as CI/CD
tools like Jenkins and ArgoCD. While the APISIX Ingress Controller project
makes significant strides in this area, APISIX itself does not provide a
comprehensive set of declarative tools to support GitOps when used in
non-Kubernetes environments such as bare metal or virtual machines.
+- **reviewability:** a pull request shows the intended configuration change;
+- **repeatability:** the same approved input can be evaluated in another
environment;
+- **traceability:** commits connect a configuration version to its reviewer
and deployment;
+- **drift detection:** a diff can reveal changes made outside the controlled
workflow;
+- **recovery:** an earlier reviewed configuration is available as a rollback
candidate.
-In traditional API gateway management, configurations and policies are
typically manipulated using imperative methods, requiring manual modifications
through command-line tools or management interfaces. This approach poses
several challenges:
+These properties depend on repository controls and deployment discipline. A
declarative file can still contain an unsafe route, and synchronizing an old
file can remove a valid production change.
-- **Cumbersome Configuration Management**: Manual modifications of
configurations are prone to errors, especially when dealing with large-scale
gateways.
+## What ADC Provides
-- **Poor Traceability**: Tracking the change history and version control of
configurations becomes difficult.
+The current ADC command set includes workflows for:
-- **Lack of Consistency**: Configuration discrepancies among multiple
environments result in inconsistencies between development, testing, and
production environments.
+- `adc lint` — check a declarative file before deployment;
+- `adc diff` — compare a local file with the configured gateway;
+- `adc sync` — synchronize the local desired state;
+- `adc dump` — export supported configuration from the gateway;
+- `adc convert openapi` — convert an OpenAPI document to declarative gateway
configuration;
+- `adc ping` — verify that ADC can connect to the configured server.
-The APISIX development team recognized several benefits of supporting GitOps
in a declarative manner to effectively address these challenges:
+Use `adc --help` and the [official ADC
repository](https://github.com/api7/adc) for the exact flags supported by the
installed release. Pin and test a tool version in automation rather than
silently changing behavior when a new release becomes available.
-1. **Improved Developer Efficiency**: By using GitOps with a declarative
configuration approach, developers can directly manage API gateway
configurations by modifying and committing configuration files in the code
repository. This method aligns with the development workflow that developers
are familiar with, reducing the learning curve and tool-switching costs, and
thus enhancing developer productivity.
+The Apache APISIX backend has version-specific compatibility boundaries and
known limitations. In [ADC
v0.30.0](https://github.com/api7/adc/blob/v0.30.0/libs/backend-apisix/README.md),
this backend is experimental, and the tested-version matrix ends at APISIX
3.17.x; APISIX 3.18.x is not listed and is therefore untested. The same release
does not support external `upstream_id` references or `plugin_configs`,
excludes Consumer Groups from dump and sync, and may report some normalized
reso [...]
-2. **Enhanced Operational Reliability**: Storing configuration files in a
version control system ensures consistency and reliability. Each configuration
change can be traced through its change history, and it becomes easy to roll
back to a previous configuration state. This function enables traceability and
auditability and reduces the risk of failures caused by human errors.
+## Install ADC
-3. **Streamlined Multi-Environment Management**: Managing different
configurations across development, testing, and production environments can be
simplified. By utilizing GitOps, it becomes effortless to create different
branches or tags for managing configuration files in different environments,
ensuring consistency across environments and reducing manual configuration
errors.
+The official installation script is:
-4. **Facilitated Team Collaboration**: The GitOps workflow promotes
collaboration and communication among team members. Developers can actively
participate in the development and maintenance of API gateway configurations
through practices such as submitting merge requests and code reviews, thereby
improving team collaboration efficiency and code quality.
+```shell
+curl -sL "https://run.api7.ai/adc/install"; | sh
+```
-## How Does APISIX Support GitOps Declarative Configuration
+Downloading and executing a remote script is a trust decision. In a controlled
environment, inspect the installer, verify the downloaded artifact according to
your supply-chain policy, and pin the version used by CI.
-### ADC and Its Usage Scenarios and Functions
+Confirm that the command is available:
-ADC, APISIX declarative CLI, is a declarative configuration tool for APISIX.
It assists users in achieving various integrations in non-Kubernetes
environments using a declarative approach.
+```shell
+adc --help
+```
-ADC allows interaction with APISIX instances through the command line and
currently provides the following functionalities:
+## Configure a Target Securely
-- **Configuration of connection information**: ADC allows the configuration of
the address, port, login token, and other details of the APISIX instance to
connect to.
-- **Configuration validation**: ADC provides the functionality to validate the
syntax of APISIX configuration files.
-- **Configuration synchronization**: Local configuration files can be
synchronized to the APISIX instance using ADC.
-- **Configuration export**: ADC enables the export of configuration files from
the APISIX instance.
-- **Configuration diff comparison**: ADC can compare the differences between
the local configuration and the configuration on the APISIX instance.
-- **OpenAPI conversion**: ADC can convert OpenAPI specification files into
APISIX configuration files.
-- **Runtime diagnostics**: ADC supports diagnostic commands such as ping to
assist in debugging the connection between ADC and the gateway.
+ADC reads connection settings from environment variables. For an APISIX
target, configure the server and credential according to the current ADC
documentation:
-In essence, ADC provides a declarative approach to APISIX configuration and
management, eliminating the need for manual calls to the admin API or using
tools like the Dashboard. Instead, configuration synchronization can be
achieved through simple commands.
+```shell
+export ADC_SERVER="https://gateway-admin.example.com";
+export ADC_TOKEN="<token-from-secret-store>"
-## How Does APISIX Use ADC for Declarative Configuration
+adc ping
+```
-### Installing APISIX and ADC
+Do not commit `ADC_TOKEN`, print it in CI logs, or expose the APISIX Admin API
to the public internet. Retrieve credentials from the CI platform's protected
secret store, restrict network access to the administrative endpoint, and grant
only the access required for the deployment job.
-Please refer to the [APISIX
documentation](https://apisix.apache.org/docs/apisix/getting-started/README/)
for installing APISIX. Once APISIX is installed, you can proceed to install the
ADC binary to the `$GOPATH/bin` directory using the `go install` command.
+ADC also supports a backend selection for supported non-default targets, such
as `ADC_BACKEND=api7ee` for the documented API7 Enterprise workflow. Do not
copy a backend setting between products without checking the current tool
documentation.
-```shell
-go install github.com/api7/adc@latest
-```
+## Create a Baseline
-Add this line of code to your `$PATH` environment variable:
+If a gateway already has configuration, export the supported state with
resource IDs to start a reviewed baseline:
```shell
-export PATH=$PATH:$GOPATH/bin
+adc dump --with-id -o adc.yaml
```
-If you don't have Go installed, you can download the latest `adc` binary and
add it to your `/bin` folder:
+For an existing gateway, `--with-id` is important: without stable IDs, a later
synchronization can treat exported resources as new objects, delete and
recreate them, and break references or traffic. Review the exported file before
treating it as the source of truth. Remove environment-specific or sensitive
values according to the resource schema and your secret-management design. An
export is a snapshot, not proof that every existing policy is correct.
+
+Commit the reviewed baseline only after confirming that:
+
+- the file contains the intended resources;
+- secret material is not stored in plaintext;
+- identifiers and references are stable across environments or templated
safely;
+- synchronizing the file in a disposable environment produces the expected
state.
+
+## Validate and Compare a Change
+
+After editing `adc.yaml`, run a local check:
```shell
-wget
https://github.com/api7/adc/releases/download/v0.2.0/adc_0.2.0_linux_amd64.tar.gz
-tar -zxvf adc_0.2.0_linux_amd64.tar.gz
-mv adc /usr/local/bin/adc
+adc lint -f adc.yaml
```
-You can find binaries for other operating systems on the [releases
page](https://github.com/api7/adc/releases/tag/v0.2.0). In the future, these
files will be published on package management tools like Homebrew.
+Linting detects supported structural problems; it cannot prove that upstream
addresses, authentication design, traffic limits, or business behavior are
correct.
-Run the following code to confirm that `adc` has been installed:
+Compare the proposed file with the configured target:
```shell
-adc --help
+adc diff -f adc.yaml
```
-If everything goes well, you will see a list of available subcommands and
using guide.
+Review additions, changes, and deletions carefully. A deletion may be
intentional, or it may mean that the desired-state file is incomplete. Treat
unexpected drift as an investigation, not an automatic reason to overwrite
production.
-### Configuring ADC with APISIX Instance
+## Synchronize Approved Configuration
-Next, configure the APISIX instance in the ADC.
+After review and environment-specific checks, synchronize the file:
```shell
-adc configure
+adc sync -f adc.yaml
```
-It will prompt you to pass in the APISIX server address
('http://127.0.0.1:9180' if you followed along) and token. If everything is
filled in correctly, you can see the following content:
+Do not run `sync` against production until the pinned ADC and APISIX versions
have completed a dump, diff, and synchronization round trip in a disposable
environment, including review of every deletion and an inventory of resources
that ADC does not manage.
-```shell
-ADC configured successfully!
-Connected to APISIX successfully!
-```
+Run synchronization from a single controlled job for each target. Concurrent
writers—CI jobs, manual Admin API changes, dashboards, and other
controllers—can race or continually overwrite one another. Define which system
owns each resource and how emergency changes are reconciled back into version
control.
-You can use the `ping` subcommand to check the APISIX connection at any time:
+After synchronization, verify both configuration and behavior:
```shell
-adc ping
+adc diff -f adc.yaml
```
-### Validating APISIX Configuration Files
-
-Create a basic APISIX configuration with a route that forwards traffic to
upstreams:
-
-```yaml title="config.yaml"
-name: "Basic configuration"
-version: "1.0.0"
-services:
- - name: httpbin-service
- hosts:
- - api7.ai
- upstream:
- name: httpbin
- nodes:
- - host: httpbin.org
- port: 80
- weight: 1
-routes:
- - name: httpbin-route
- service_id: httpbin-service
- uri: "/anything"
- methods:
- - GET
-```
+Also run route-level smoke tests and observe error rate, latency, and upstream
health. A zero configuration diff does not prove that the deployed routes work.
-Once the ADC is connected to the running APISIX instance, you can use it to
validate this configuration before applying it by running:
+## Convert an OpenAPI Document
+
+ADC can create a starting configuration from an OpenAPI document:
```shell
-adc validate -f config.yaml
+adc convert openapi -f openapi.yaml -o adc.yaml
```
-If the configuration is valid, you will receive a response similar to:
+Review the generated file. An OpenAPI document describes an HTTP interface,
but it normally does not contain every gateway concern, such as upstream
discovery, production credentials, consumer policy, rate-limit capacity, or
observability requirements. Conversion is a bootstrap step, not an automatic
production deployment.
-```shell
-Read configuration file successfully: config name: Basic configuration,
version: 1.0.0, routes: 1, services: 1.
-Successfully validated configuration file!
-```
+## A Safe GitOps Pipeline
-### Syncing Configuration to APISIX Instance
+A minimal pipeline can use the following stages.
-ADC can now be used to synchronize valid configurations with connected APISIX
instances. To do this, run:
+### 1. Pull-request checks
-```shell
-adc sync -f config.yaml
-```
+- validate YAML and repository conventions;
+- run `adc lint` on every changed declarative file;
+- reject embedded secrets;
+- apply policy checks for administrative exposure, unauthenticated routes,
wildcard hosts, and unbounded traffic where appropriate;
+- require review from the service owner and gateway platform owner for
sensitive changes.
-This will create a route and a service as we declared in the configuration
file:
+### 2. Disposable-environment test
-```shell
-creating service: "httpbin-service"
-creating route: "httpbin-route"
-Summary: created 2, updated 0, deleted 0
-```
+Synchronize the change to a non-production gateway, then run authentication,
routing, timeout, and negative tests. Test deletion and rollback paths as well
as successful creation.
-To verify that the route was created correctly, let's try sending a request:
+### 3. Target diff
-```shell
-curl localhost:9080/anything -H "host:api7.ai"
-```
+Run `adc diff` against the intended environment immediately before deployment.
Store a redacted diff as deployment evidence and stop on unreviewed destructive
changes.
-If everything is correct, you will receive a response from
[httpbin.org](httpbin.org).
-
-### Comparing Local and Running Configuration
-
-Now, let's update the local configuration in the `config.yaml` file by adding
another route:
-
-```yaml title="config.yaml" {20-24}
-name: "Basic configuration"
-version: "1.0.0"
-services:
- - name: httpbin-service
- hosts:
- - api7.ai
- upstream:
- name: httpbin
- nodes:
- - host: httpbin.org
- port: 80
- weight: 1
-routes:
- - name: httpbin-route-anything
- service_id: httpbin-service
- uri: "/anything"
- methods:
- - GET
- - name: httpbin-route-ip
- service_id: httpbin-service
- uri: "/ip"
- methods:
- - GET
-```
+### 4. Controlled synchronization
-Before synchronizing this configuration with APISIX, ADC allows you to check
the differences between it and the existing APISIX configuration. You can run
the following operations:
+Use protected environments, one writer, a pinned ADC version, short-lived
credentials where available, and an auditable approval. Do not pass secrets as
command-line arguments that may be captured in process or job logs.
-```shell
-adc diff -f config.yaml
-```
+### 5. Post-deployment verification
-You can see the added and deleted configurations and check the changes before
applying the configuration.
-
-### Converting OpenAPI Definitions to APISIX Configurations
-
-ADC also supports the use of [OpenAPI
definitions](https://spec.openapis.org/oas/v3.0.0). ADC allows the conversion
of OpenAPI format definitions into APISIX configurations.
-
-For example, if you document your API in OpenAPI format like this:
-
-```yaml title="openAPI.yaml"
-openapi: 3.0.0
-info:
- title: httpbin API
- description: Routes for httpbin API
- version: 1.0.0
-servers:
- - url: http://httpbin.org
-paths:
- /anything:
- get:
- tags:
- - default
- summary: Returns anything that is passed in the request data
- operationId: getAnything
- parameters:
- - name: host
- in: header
- schema:
- type: string
- example: "{{host}}"
- responses:
- "200":
- description: Successfully return anything
- content:
- application/json: {}
- /ip:
- get:
- tags:
- - default
- summary: Returns the IP address of the requester
- operationId: getIP
- responses:
- "200":
- description: Successfully return IP
- content:
- application/json: {}
-```
+Confirm the target diff, run smoke tests, monitor key traffic indicators, and
associate the deployment with the source commit. Roll back only after
evaluating whether the previous file remains compatible with current upstream
services.
-You can convert this to an APISIX configuration using the subcommand
`openapi2apisix` as follows:
+## Environment Promotion
-```shell
-adc openapi2apisix -o config.yaml -f openAPI.yaml
-```
+Avoid maintaining unrelated copies of a large configuration file for
development, staging, and production. Choose a controlled strategy such as:
-This will create a configuration file as shown below:
-
-```yaml title="config.yaml"
-name: ""
-routes:
-- desc: Returns anything that is passed in the request data
- id: ""
- methods:
- - GET
- name: getAnything
- uris:
- - /anything
-- desc: Returns the IP address of the requester
- id: ""
- methods:
- - GET
- name: getIP
- uris:
- - /ip
-services:
-- desc: Routes for httpbin API
- id: ""
- name: httpbin API
- upstream:
- id: ""
- name: ""
- nodes: null
-version: ""
-```
+- a shared base plus small reviewed environment overlays;
+- generated environment files from a typed source and validated templates;
+- separate directories with automated structural comparison.
-As you can see, the configuration is incomplete and a lot of configuration
still needs to be added manually. We are improving ADC to bridge the gap
between OpenAPI definitions and configurations that can be mapped directly to
APISIX.
+Keep secrets outside the declarative source and resolve them through supported
secret references or the deployment environment. Ensure the rendered artifact
being synchronized is reviewable and retained as deployment evidence without
secret values.
-### Tip: Use Autocomplete
+## Drift and Emergency Changes
-ADC offers many functions, and the list of features is sure to grow. To learn
how to use any subcommand, you can use the `--help` or `-h` flag, which will
display the documentation for that subcommand.
+Decide in advance how to handle a manual emergency edit:
-To make it even easier, you can use the `completion` subcommand to generate an
autocompletion script for your shell environment. For example, if you are using
a zsh shell, you can run:
+1. record who made it, why, and which resource changed;
+2. export or inspect the resulting state;
+3. reconcile the intended change into version control promptly;
+4. verify that the next synchronization will not remove the emergency fix
accidentally.
-```shell
-adc completion zsh
-```
+Blindly running `adc sync` on a timer can hide ownership problems and
repeatedly revert another authorized controller. Alert on drift first;
reconcile automatically only when the resource ownership and desired state are
unambiguous.
+
+## Frequently Asked Questions
+
+### Is APISIX standalone mode the same as ADC?
+
+No. Standalone mode is an APISIX deployment/configuration mode using a local
YAML configuration source. ADC is a separate CLI that compares and synchronizes
supported declarative resources with a configured backend. Choose the model
that fits the deployment architecture and do not let multiple writers own the
same resources.
+
+### Does `adc lint` guarantee a safe production change?
+
+No. It checks supported file rules. Security, upstream reachability, capacity,
compatibility, and deletion impact require policy and integration tests.
+
+### Should CI automatically synchronize every merged change?
+
+Only if the repository, approval, credential, environment, and rollback
controls justify it. Sensitive production environments may require a protected
deployment approval even after the source pull request is merged.
-You can then copy and paste the output into your `.zshrc` file and it will
start showing hints when you use `adc`.
+### Can ADC eliminate configuration drift?
-ADC is still in its infancy and is constantly being improved. To learn more
about the project, report a bug, or suggest a feature, visit
[github.com/api7/adc](github.com/api7/adc).
+It can show and reconcile supported differences. Preventing repeated drift
requires clear ownership and removing uncontrolled writers, not only running
another synchronization.
-## Summary
+## Conclusion
-By using the declarative configuration tool ADC, APISIX provides a more
simplified, reliable, and traceable management method, allowing developers to
manage and deploy API gateway configurations more efficiently. This new feature
brings many benefits to team collaboration, environmental consistency, and
configuration management, providing strong support for building reliable
cloud-native architectures.
+ADC provides useful primitives for a declarative APISIX workflow: export,
lint, compare, synchronize, convert, and test connectivity. A reliable GitOps
process combines those commands with protected secrets, review, one-writer
ownership, environment testing, drift handling, and post-deployment
verification.
-In non-Kubernetes environments, users can seamlessly integrate tools like
Jenkins and ArgoCD. They can leverage GitOps' internal CI/CD approach to manage
various aspects of APISIX, enabling functions like multi-environment releases.
+Keep the desired state auditable, treat every unexpected deletion as a risk,
and make the synchronized artifact—not an operator's workstation—the
reproducible input to the gateway deployment.
diff --git
a/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md
b/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md
index 390ef65e28a..e9df6798746 100644
--- a/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md
+++ b/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md
@@ -1,5 +1,5 @@
---
-title: "Cloud vs Open Source vs Commercial API Gateways"
+title: "Cloud-Managed vs Open Source vs Commercial API Gateways"
authors:
- name: Ming Wen
title: Author
@@ -18,144 +18,133 @@ keywords:
- Hybrid Cloud
- Vendor Lock-in
- API Strategy
-description: "Compare cloud-managed, open-source, and commercial API gateways,
and learn where Apache APISIX fits for self-hosted API traffic management."
+description: "Compare cloud-managed, open-source, and commercial API gateways
by deployment, operations, extensibility, support, and total cost."
tags: [Ecosystem]
image:
https://static.api7.ai/uploads/2025/02/17/gWz2QJYq_api-gateway-comparison.png
---
-This article explores the differences between cloud-managed, open-source, and
commercial API gateways. It highlights key pros and cons, pricing risks, and
strategic recommendations for businesses that anticipate API growth and hybrid
cloud adoption.
+Cloud-managed, open-source, and commercial API gateways are not mutually
exclusive categories. A vendor can offer a managed service built on open-source
software, while a commercial gateway can support self-managed and hosted
deployments. The useful question is therefore not which label is universally
best, but which operating and support model matches your requirements.
<!--truncate-->
-## Introduction
+## What Are You Comparing?
-API gateways have become essential components in modern cloud architectures.
They provide security, traffic management, observability, and service
orchestration—critical for handling APIs at scale. However, with multiple API
gateway solutions available, choosing the right one can be challenging.
+An API gateway sits between API clients and upstream services. Depending on
the product and configuration, it can handle routing, authentication, traffic
limits, protocol translation, observability integrations, and other
cross-cutting policies.
-Broadly, API gateways fall into three categories:
+The three common buying models emphasize different responsibilities:
-- **Cloud API Gateways** (e.g., <a href="https://aws.amazon.com/api-gateway/";
rel="nofollow">Amazon API Gateway</a>, <a
href="https://cloud.google.com/apigee"; rel="nofollow">Google Apigee</a>)
-- **Open Source API Gateways** (e.g., [Apache
APISIX](https://apisix.apache.org/), Kong Gateway, Tyk)
-- **Commercial API Gateways** (e.g., <a href="https://www.mulesoft.com/";
rel="nofollow">MuleSoft</a>, <a href="https://boomi.com/";
rel="nofollow">Boomi</a>)
+- **Cloud-managed gateway:** the provider operates most or all of the gateway
service. The deployment is usually closely integrated with that provider's
identity, networking, logging, and billing services.
+- **Open-source gateway:** the source code and an open-source license are
available. Your team can self-manage the gateway or, for some projects, use a
vendor's managed or enterprise distribution.
+- **Commercial gateway:** a paid product or service that may include
proprietary features, support, service-level commitments, and governance
tooling. Deployment options vary by vendor.
-Each option has its advantages and trade-offs. This article provides a deep
dive into their differences, hidden risks, and a **strategic recommendation**
for companies looking to scale API usage and adopt hybrid cloud architectures.
+Because these models overlap, compare specific products and editions rather
than assuming that every product in a category behaves the same way.
-## Cloud API Gateways: Convenience vs. Lock-in
+## Cloud-Managed API Gateways
-### Pros:
+A cloud-managed gateway can reduce the amount of infrastructure a team
operates directly. It is often a strong fit when most workloads already run in
one cloud and the team values integrated provisioning and billing.
-✅ Fully managed, reducing operational burden
+Common benefits include:
-✅ Deep integration with cloud provider services (IAM, logging, monitoring)
+- provider-managed availability, upgrades, and capacity;
+- integration with the cloud provider's identity, monitoring, networking, and
serverless services;
+- usage-based billing that can make a small deployment quick to start.
-✅ High availability and auto-scaling out of the box
+Questions to evaluate include:
-### Cons:
+- Can the control plane or data plane run in every environment you require?
+- Which policies, identity integrations, or deployment definitions are
portable?
+- How do request, data-transfer, logging, and support charges change at your
expected traffic level?
+- What extension points are available for policies the service does not
provide?
-❌ **Vendor Lock-in**: API definitions, policies, and configurations are tied
to the cloud provider
+Some managed services support hybrid or multicloud patterns, while others are
designed primarily for their provider's environment. Verify the architecture of
the exact service instead of treating “cloud-managed” as “cloud-only.”
-❌ **No Customization**: Cloud API gateways are closed-source, limiting the
ability to add custom plugins or functionality
+## Open-Source API Gateways
-❌ **No Hybrid Cloud Support**: Cloud-managed API gateways cannot be deployed
on-premise or across multi-cloud environments
+An open-source gateway gives teams access to the code and can offer broad
deployment and extension choices. It does not, however, remove the cost of
operating the system.
-### Use Case:
+Common benefits include:
-Cloud API gateways are ideal for **startups and small teams** that need a
quick, managed solution without worrying about infrastructure maintenance.
However, as API traffic grows or hybrid cloud requirements arise, their
limitations become apparent.
+- visibility into the implementation and release process;
+- the ability to evaluate, extend, and self-host the software under its
license;
+- deployment choices that may include virtual machines, containers,
Kubernetes, on-premises infrastructure, and multiple clouds;
+- community integrations and a path to paid support when the project has
commercial providers.
-🔹 **Example**: Amazon API Gateway is a popular choice for cloud-native
applications but lacks flexibility for on-premises deployments.
+Operational responsibilities can include:
-## Open Source API Gateways: Control and Flexibility
+- sizing and scaling the data plane and any required control-plane components;
+- applying security updates and testing upgrades;
+- protecting configuration stores and administrative APIs;
+- building monitoring, backup, incident-response, and change-management
procedures.
-### Pros:
+License, governance, and project health also matter. Review the current
license, release activity, contributor base, security process, and ownership
model. Foundation governance can reduce dependence on a single vendor, but it
does not replace technical and operational due diligence.
-✅ Fully customizable, allowing teams to extend functionality as needed
+## Commercial API Gateways
-✅ No licensing fees, reducing costs in the long run
+Commercial products can bundle the gateway with API lifecycle, analytics,
developer portal, governance, security, and support capabilities. Some are
proprietary; others are enterprise distributions or hosted services based on an
open-source project.
-✅ Can be deployed anywhere—**on-prem, multi-cloud, hybrid cloud**
+Potential benefits include:
-### Cons:
+- vendor support and contractual service commitments;
+- packaged administration, governance, and analytics workflows;
+- tested integrations and upgrade paths;
+- features intended for larger organizations, subject to the product and
edition.
-❌ **Operational Overhead**: Requires self-hosting, upgrades, and security
management
+The trade-offs are product-specific. Evaluate:
-❌ **Governance Risks**: Some open-source projects are controlled by a single
vendor, which may later change licensing terms (e.g., Redis, ELK Stack)
+- whether pricing is based on requests, environments, gateway instances,
users, or another unit;
+- which features require higher editions;
+- how configuration and data can be exported;
+- whether the data plane continues operating if it loses contact with a hosted
control plane;
+- where control-plane and traffic data are processed;
+- whether the contract, support model, and deployment options meet your
compliance needs.
-❌ **Scalability Complexity**: Running an open-source API gateway at enterprise
scale requires expertise in deployment and maintenance
+Paid does not automatically mean more secure or more scalable, just as open
source does not automatically mean less expensive. Architecture, configuration,
operations, and support all affect the result.
-## Key Consideration: Choosing a Foundation-Owned Open Source Project
+## A Practical Comparison Framework
-Some open-source API gateways are **vendor-controlled**, meaning the company
behind them can change licensing terms. For example, Redis and Elasticsearch
modified their open-source licenses to prevent cloud providers from offering
managed services.
+Use the same workload and constraints when evaluating each candidate.
-To **avoid future licensing risks**, it's safer to choose an API gateway
governed by a **neutral open-source foundation**, such as:
+| Decision area | Questions to ask |
+| --- | --- |
+| Deployment | Where do the control plane, data plane, and configuration store
run? Can the gateway cover cloud, on-premises, edge, and Kubernetes
environments you actually use? |
+| Reliability | How does traffic handling behave during control-plane,
network, or configuration-store failures? How are upgrades and rollbacks
performed? |
+| Security | Which authentication and authorization policies are built in? How
are secrets, administrative access, audit logs, and security updates managed? |
+| Extensibility | Can you add policies safely? Which languages, plugin models,
and supported extension points are available? |
+| Operations | Who owns capacity planning, upgrades, backups, monitoring, and
incidents? What skills and staffing does that require? |
+| Portability | Can routes, policies, API definitions, and telemetry be moved
or reproduced elsewhere? Which provider-specific integrations create migration
work? |
+| Support | Is community support sufficient, or do you need response-time
commitments and a supported upgrade path? |
+| Cost | What is the three-year total cost at realistic request volume,
including infrastructure, traffic, logs, labor, licenses, and support? |
-- [Apache APISIX (Apache Software Foundation)](https://apisix.apache.org/)
-- <a href="https://www.envoyproxy.io/"; rel="nofollow">Envoy Proxy (Cloud
Native Computing Foundation)</a>
+Run a proof of concept with representative authentication, routing, failure,
and observability scenarios. A feature checklist alone will not show
operational complexity or migration risk.
-## Commercial API Gateways: Enterprise Features with Pricing Risks
+## How Apache APISIX Fits
-### Pros:
+[Apache APISIX](https://apisix.apache.org/) is an Apache Software Foundation
project and an open-source API gateway. It supports multiple deployment
approaches and a plugin-based model for traffic management, security,
observability, and protocol handling. Teams can operate APISIX themselves and
choose commercial support separately if required.
-✅ **Enterprise-grade security**
+That model can be useful when deployment control, open governance, or
extensibility is important. It also means the operating team remains
responsible for designing and running a reliable deployment unless it purchases
an appropriate managed service or support offering.
-✅ **SLA-backed support** with 24/7 assistance
+Before selecting it, validate the plugins, deployment mode, configuration
workflow, performance profile, and operational model against your own
requirements. For a product-focused comparison, see the [open-source API
gateway comparison](/learning-center/open-source-api-gateway-comparison/). To
distinguish gateway functions from broader lifecycle tooling, see [API gateway
vs API management](/learning-center/api-gateway-vs-api-management/).
-✅ **Monetization and API analytics** for businesses offering APIs as a service
+## Frequently Asked Questions
-### Cons:
+### Is an open-source API gateway always cheaper?
-❌ **High Licensing Costs**: Typically charged per API call, which can become
expensive
+No. The software may not require a commercial license, but infrastructure,
engineering time, observability, security maintenance, and support still
contribute to total cost. Compare the complete operating model over the
expected lifetime of the system.
-❌ **Potential Pricing Changes**: Many vendors modify pricing models over time,
significantly increasing costs (e.g., Apigee, Kong Enterprise)
+### Does a managed API gateway always cause vendor lock-in?
-❌ **Limited Deployment Flexibility**: Some solutions require vendor-managed
infrastructure, reducing control
+Not necessarily. Migration effort depends on provider-specific policies,
identity services, deployment definitions, observability integrations, and data
formats. A portable API specification helps, but it rarely captures the entire
gateway configuration.
-### Use Case:
+### Is a commercial gateway required for enterprise use?
-Best suited for **large enterprises** with strict security, compliance, and
SLA requirements. However, pricing unpredictability is a concern—many companies
have faced sudden cost increases.
+No. Some organizations operate open-source gateways at scale; others prefer
commercial support and packaged governance. The right choice depends on
internal expertise, risk tolerance, compliance needs, and service commitments.
-## Strategic Recommendation: A Hybrid Approach for Growth
+### Which model is best for hybrid or multicloud deployments?
-If your API traffic is **growing rapidly** and **hybrid cloud** is part of
your strategy, the best approach is:
+There is no category-wide answer. Compare where each product's control and
data planes can run, how configuration is distributed, what happens during loss
of connectivity, and which features depend on a specific cloud.
-**1. Start with an Open Source API Gateway**
+## Conclusion
-- Avoid vendor lock-in
-- Maintain control over deployment and customization
-- Lower costs by eliminating per-call fees
+Choose an API gateway by responsibility and architecture, not by category
label alone. A cloud-managed service can reduce operational work, an
open-source gateway can provide code access and deployment control, and a
commercial offering can add support and packaged workflows. Many products
combine elements of all three.
-**2. Upgrade to a Commercial Version When Needed**
-
-- When security requirements increase
-- When managing multi-cluster deployments
-- When enterprise support and SLAs become necessary
-
-By following this approach, you get the best of both worlds: flexibility, cost
control, and enterprise-grade features when needed.
-
-🔹 **Example Strategy**: A company starts with Apache APISIX (open source) and
later upgrades to [API7 Enterprise](https://api7.ai/) when requiring advanced
security and SLA support.
-
-## FAQ: Common Questions About API Gateway Selection
-
-**1. Why not start with a cloud API gateway and switch later?**
-
-Switching API gateways is complex due to differences in configurations,
rate-limiting rules, authentication methods, and monitoring setups. If hybrid
cloud or multi-cloud is part of your strategy, starting with an open-source
gateway ensures long-term flexibility.
-
-**2. How do I avoid open-source licensing risks?**
-
-Choose projects governed by neutral software foundations (e.g., Apache
Software Foundation, CNCF). Avoid projects fully controlled by a single
company, as they may change their licensing model.
-
-**3. What is the best API gateway for hybrid cloud?**
-
-Open-source gateways like Apache APISIX and Envoy Proxy offer full deployment
flexibility, making them ideal for hybrid and multi-cloud architectures.
-
-## Conclusion: Making the Right Choice
-
-Choosing the right API gateway depends on your **scalability, budget, and
cloud strategy**:
-
-| Criteria | Cloud API Gateway | Open Source API
Gateway | Commercial API Gateway |
-|---------------------------|----------------------------|----------------------------|----------------------------|
-| **Cost** | High (Pay per API call) | Low (Free)
| High (License fees) |
-| **Customization** | Limited | Full control
| Limited |
-| **Deployment Flexibility** | Cloud-only | Anywhere
(Hybrid, Multi-cloud) | Varies |
-| **Enterprise Features** | Basic | Requires
customization | Advanced (Security, Compliance) |
-| **Support** | Cloud provider support |
Community-driven | SLA-backed |
-
-If **API traffic is growing rapidly** and **hybrid cloud adoption is
planned**, a **hybrid approach**—starting with **open source** and upgrading to
a **commercial enterprise solution** when needed—offers the best flexibility
and cost efficiency.
+Document your deployment, reliability, security, portability, support, and
cost requirements; test the finalists with a realistic workload; and select the
operating model your team can sustain.
