Why teams proxy gRPC services through Apache APISIX
Teams proxy gRPC services through Apache APISIX when they want one edge in front of internal or partner gRPC APIs for authentication, rate limits and observability, instead of configuring each service separately. The usual situation is a set of services that were built on gRPC for speed and strong contracts, now exposed to other business units, mobile apps or external partners, and each needing the same access controls. Putting a gateway in front lets the security and platform teams manage those controls in one place, while service owners keep their protobuf contracts and code.
The APISIX repository lists gRPC proxying alongside HTTP and HTTPS, WebSocket and TCP/UDP proxying, so gRPC traffic is handled by the same gateway that fronts your REST APIs. That shared footprint is useful, but the effort in a gRPC project sits in decisions rather than installation. Teams need to decide how methods map to routes, whether the gateway talks to backends over TLS and how it verifies their certificates, which identities are accepted at the edge, and how limits are counted for long-lived streams. Confirm with your own architects which gRPC services are unary, which use streaming, and which clients can speak native gRPC at all, because those answers change the route design more than any setting does.
The first working step is usually a small pilot: one service, one upstream, and a route that you can test with a real client from the networks your callers use. Check the APISIX release you plan to run against the APISIX downloads page and the release notes before you pin a version, since certificate verification behavior for gRPC upstreams has changed between releases. Use the pilot to settle your identity and TLS choices before you copy the pattern to other services.
Native gRPC, transcoding or gRPC-Web: which path fits your clients
Service-to-service callers that already speak gRPC are the simplest case. They send HTTP/2 requests with protobuf payloads, so APISIX proxies the traffic as gRPC without converting it. The gateway's job is to route by service and method, terminate or pass through TLS, and apply authentication and rate limits to the calls. The client team keeps its generated stubs, and the gateway needs no proto files for simple proxying.
- Client requirement: callers must support HTTP/2 and gRPC, and they keep their generated code from the service's
.protofiles. - Proto ownership: the service team owns the definitions, and the client teams pin versions they generate from.
- Gateway configuration: routes match on the gRPC path, and the upstream is set to HTTP/2 with the right scheme for the backend.
- TLS to backends: confirm whether the backend uses
grpcsand which CA bundle APISIX should trust before you turn on verification. - Policy: authentication and rate limits apply to the method path, so confirm which headers and identities your plugins can read.
Before you choose this path, ask each service team which callers they have and whether any of them cannot run a gRPC client.
Some clients send HTTP requests with JSON bodies, such as scripts, partner integrations or mobile teams that do not want to ship gRPC libraries. The grpc-transcode plugin converts these requests to gRPC and converts the responses back to JSON, using protobuf definitions that you upload through the Admin API protos endpoint. The gateway then holds a copy of the schema, so the proto files become a runtime dependency of the route.
- Client requirement: callers send JSON over HTTP, and the field names and types must match the protobuf messages.
- Proto ownership: name a team that owns the uploaded definitions and approves changes, because a stale copy will misroute or break requests.
- Admin API use: the protos are uploaded and managed through the Admin API, so restrict who can reach that endpoint.
- Error mapping: test how gRPC status codes and error details appear in the JSON responses your clients parse.
- Streaming limits: confirm which streaming methods the plugin supports in your APISIX version before you promise them to a client team.
Ask the service owners whether they can publish a stable proto set for transcoding, and check the plugin documentation for the methods you need.
Browser apps cannot make native gRPC calls because browsers do not expose the HTTP/2 framing that gRPC needs. gRPC-Web is a browser-compatible variant, and the grpc-web plugin lets APISIX translate browser requests to gRPC for the backend. This path also brings CORS and header settings into scope, because the browser enforces them before any gRPC traffic reaches the gateway. The detailed setup, content types and alternatives are covered in the sibling topic on gRPC-Web for browser clients.
- Client requirement: the front-end build uses a gRPC-Web client library generated from the same proto files as the backend.
- Proto ownership: front-end and back-end teams share the definitions, so agree on a release process for changes.
- CORS and headers: allowed origins, methods and headers must be set on the route, and tests should run from real browser origins.
- Authentication: decide how tokens reach the browser flow and confirm the gateway checks them on each call.
- Alternatives: some teams find that JSON transcoding or an Envoy sidecar is simpler for browser apps, so compare them before you commit.
Before you build, check which browser apps need gRPC and whether their front-end team will maintain the generated client code.
How to set up a gRPC route in APISIX
This sequence takes a gRPC backend from an unverified service to a route that APISIX forwards over HTTP/2, with TLS trust set deliberately and a real client call confirming each hop. Each step ends with a check you can run before moving on.
Confirm the backend speaks HTTP/2 and gRPC
Your platform engineer or the service owner confirms that the backend listens for HTTP/2 and decides whether it serves plaintext gRPC (grpc) or TLS-protected gRPC (grpcs). Ask the service owner for the host, port and whether the certificate is issued by a public or private certificate authority. Run a direct gRPC call against the backend, bypassing the gateway, using a client such as grpcurl. The step is done when a unary method returns a response from the backend itself, which gives you a known-good baseline to compare against later.
Create the upstream with the matching scheme
Create an upstream in APISIX through the Admin API or your configuration source, setting the scheme to grpc for plaintext backends or grpcs for TLS backends, and listing the backend nodes with their ports. Keep the upstream as a separate object so that routes, certificate trust and health settings can change without touching the service. Confirm the upstream is stored by reading it back from the Admin API. The step is done when the stored object shows the expected scheme and node addresses, and the nodes are reachable from the gateway host, which you can test with a basic TCP connection from that machine.
Define the route with gRPC method matching
Create the route and match the gRPC method path, which takes the form of the service name and method name in the HTTP/2 path, so that only the methods you intend to expose reach the upstream. Attach the upstream you created in the previous step. Keep the match narrow at first, for example one service and one method, and widen it after testing. Check that the route is enabled and that APISIX has loaded it. The step is done when a request to the exact method succeeds through the gateway port, and a request to a method not listed in the route returns an error rather than reaching the backend.
Configure TLS trust for grpcs upstreams
For a grpcs backend, set the upstream TLS options so APISIX verifies the backend certificate chain and hostname, using a trusted CA bundle that your security team approves. Set the verification option explicitly rather than relying on defaults you have not inspected, and check the APISIX release notes for your version, because verification behavior for https and grpcs upstreams changed in 3.19.0 and upstreams already marked for verification will start rejecting untrusted certificates. Ask your security team who owns the private CA and how rotation is handled. The step is done when the gateway accepts the backend certificate and the error log shows no handshake failures during a test call.
Test a unary call through the gateway
Use the same gRPC client you used in the first step, but point it at the APISIX gateway address and route path. Send a unary request for a matched method and compare the response with the direct backend response. Confirm that the status code is OK and the payload matches. If the call fails, check the route match, the scheme on the upstream, and the gateway access log for the upstream response. The step is done when the gateway response matches the direct backend response for a representative set of request payloads, including one with a larger message body.
Prove that untrusted certificates are rejected
Point a temporary upstream node at a backend or test listener that presents a certificate from an untrusted authority, or a certificate whose name does not match the upstream host, and send a unary call through the route. The gateway should refuse the connection and return an error. This negative test proves that TLS verification is active, which a successful positive call alone does not show. Record the error for your change ticket and remove the test node afterwards. The step is done when the rejected call appears in the gateway error log with a certificate-related message and the production upstream still accepts valid calls.
Document the route and confirm the test evidence
Record the upstream and route definitions as stored in your configuration source, the CA bundle reference, the matched methods, and the outputs of the positive and negative tests. Store the client commands alongside them so the checks can be repeated after an upgrade or a change to certificates. Ask your security or compliance lead which of these records they need for change approval. The step is done when someone who did not run the tests can reproduce the positive call and the rejected untrusted call from the documented steps and reach the same results.
What the 3.19 verification change means for grpcs upstreams
APISIX 3.19.0 honours `upstream.tls.verify` for grpcs upstreams, not only for Kafka. Any gRPC route that points at a grpcs upstream and already sets verify: true will start rejecting backend certificates it cannot validate once the gateway is upgraded. Before the upgrade, these settings may have been silently ignored for gRPC, so a certificate problem that was invisible yesterday can cause failed calls the morning after. Treat this as a behavior change to plan for, not as a routine patch.
The earlier change in 3.12.0 also matters here. That release set ssl_trusted_certificate to the system certificate store by default, according to the APISIX changelog. Backends signed by a public CA usually validate against the system store, but backends signed by an internal or private CA may not, unless that CA is installed on the gateway hosts or referenced explicitly. Check the changelog entries for both releases and confirm how your own gateway images and packages populate the trust store, since this depends on your build and distribution.
Start with an inventory. List every upstream that uses the grpcs scheme or https scheme with verify set to true, and record which certificate authority signs each backend. Then reproduce the upgrade in staging with the same trust store, the same private CA chains and the same gRPC clients, and confirm each method still succeeds. Test certificate rotation and intermediate chains too, because a chain that validates today may fail once a backend renews. Ask your APISIX support provider or internal platform team to confirm the exact rollback path for your deployment before the production window.
Questions teams ask before proxying gRPC through APISIX
What does a gRPC proxying engagement cost and what drives the effort?
The cost follows from a written scope, and the largest drivers are the size of the proto inventory, the number of services and methods that need routes, and how far TLS and identity need to reach. A small set of unary services with one identity provider is a very different job from dozens of streaming services with mutual TLS to backends and per-method rate limits. Ask for a quote that lists the proto files and services in scope, each upstream and its TLS setup, the authentication plugins per route, the rate limit policies, and the environments to be built. Most of the cost is one-time design and build, with a smaller recurring part for upgrades and support if you choose a retainer. DeployOpen does not publish a price list, so the written scope is the basis for any figure.
How long does it take to proxy gRPC services through APISIX?
Duration depends on the scope, not on a fixed template. The main variables are how many services and methods are proxied, whether you need native gRPC, transcoding or gRPC-Web, how many backends use TLS, and whether authentication must be integrated with an existing identity provider. Work that involves unfamiliar protos or backends that have never been tested behind a proxy usually takes longer than work where the contracts are stable and documented. DeployOpen agrees timelines in writing as part of a fixed-scope engagement, so ask for the milestones and the assumptions behind each one, including what must be ready from your side before the build starts.
What must our team provide before the work starts?
Most delays come from inputs that are not ready, so prepare these before kickoff:
- The
.protofiles for every service in scope, with their import dependencies and the versions your clients use. - The certificates and CA chain for the gRPC backends, plus the trust bundle that APISIX should use when it verifies them.
- Details of your identity provider, such as the issuer, client registrations, scopes and the claims that map to roles.
- A list of client types, including whether any browser clients need gRPC-Web.
- Access to the environments where APISIX and the backends will run, and the names of people who approve certificate and identity changes.
The written scope should state who supplies each item and by when.
Can our own team build gRPC proxying on APISIX without a partner?
Yes, if your team already runs APISIX, understands HTTP/2 and gRPC behavior, and has people who can manage the proto contracts and certificates. The skills that matter most are protobuf handling, TLS trust configuration, identity integration and load test design. Many teams keep the routine route work in-house and bring in a partner for the parts that carry the most risk, such as the first TLS verification rollout, the authentication design or the upgrade test plan. Whichever path you choose, confirm the specific behavior for your APISIX version against the project documentation and the changelog rather than relying on older examples.
How does the 3.19 verification change affect an upgrade?
APISIX 3.19.0 honors upstream.tls.verify for grpcs upstreams, as well as for HTTPS upstreams and Kafka. An upstream that already sets verify: true will start rejecting backend certificates it does not trust, so a gRPC route that worked before can fail after the upgrade. Before upgrading, list every grpcs upstream with verification enabled, confirm that each backend certificate chains to a trusted root, and check the trust store that APISIX uses. The 3.12.0 change that set ssl_trusted_certificate to the system store by default is also relevant when backends use private CAs. Test these paths in a staging environment that matches production certificates before changing live routes.
Who is responsible for certificate and trust configuration during the project?
Responsibility is split between the people who own the certificates and the people who configure the gateway. Your team usually owns the issuing CA, the certificate lifecycle and the decision about which roots are trusted, while the implementation team configures the upstream TLS settings, the trust store references and the test cases that prove a backend is accepted or refused. Write this split into the scope, because an unclear boundary here is the most common reason a verification change breaks production traffic. Ask for a runbook that covers certificate rotation for each grpcs backend and who approves a change.
Does a gRPC proxying project cover ongoing support after go-live?
The fixed-scope build ends with the agreed deliverables, which typically include configuration, documentation and verification evidence. Ongoing work, such as APISIX upgrades, new services added to the proxy, certificate rotation support and continuous testing, can be covered by a retainer that is agreed separately. Ask for the deliverables list, the handover format and what happens to documentation when a new APISIX release changes behavior. Keep the upgrade decision with your team, supported by a written test plan, so that each new release is checked against your own gRPC routes before it reaches production.
Configuration options for gRPC routes and when each fits
This table compares the main ways to expose a gRPC service through APISIX: native gRPC upstreams, grpc-transcode, and gRPC-Web. It also covers the upstream scheme and TLS verification settings that change how the gateway connects to backends. Read each row against your client types and your backend certificate setup, and confirm exact field names in the plugin documentation before you configure anything.
| Option | What it does | When it fits | Trade-off |
|---|---|---|---|
| Native gRPC upstream | Proxies gRPC over HTTP/2 from client to backend with the upstream scheme set to grpc or grpcs | Clients already speak gRPC and backends expose gRPC directly | Clients must support HTTP/2 and gRPC, and the gateway passes method-level traffic without translating payloads |
| grpc-transcode plugin | Converts HTTP and JSON requests into gRPC calls and converts responses back, using protobuf definitions uploaded through the protos Admin API endpoint | Web or mobile clients or partners send JSON over HTTP and cannot use gRPC clients | You must store and update protobuf definitions in the gateway, and transcoding adds a conversion layer to test |
| gRPC-Web | Lets browser apps call gRPC services through the grpc-web plugin using the gRPC-Web wire format | Browser single-page apps need direct access to existing gRPC services | Browser-specific content types, CORS and allowed headers need explicit configuration; confirm defaults in the plugin documentation |
| Route matching by service and method | Matches requests on the gRPC path, which includes the service and method names, so routes can target individual methods | Different methods need different upstreams, authentication or rate limits | Route counts grow with method count, so review how many routes a service needs before you design them |
| TLS verification (upstream.tls.verify) | Controls whether the gateway checks the backend certificate for grpcs upstreams | Backends use certificates from a private or public CA that the gateway should trust | From APISIX 3.19.0, verify: true rejects untrusted certificates, so confirm trust chains before upgrading |
| Trusted CA bundle (ssl_trusted_certificate) | Sets the CA store the gateway uses when verifying upstream certificates | Backends use a private CA or a CA not in the default store | The system store is the default from 3.12.0, so private CAs must be added explicitly; confirm the setting in the configuration reference |
| Authentication and rate limits on gRPC routes | Plugins attach to the route, so authentication and traffic limits apply to matched gRPC methods | Callers need per-consumer keys, tokens or quotas for specific methods | Plugin behavior on HTTP/2 streams and trailers should be tested for each plugin you use; confirm compatibility in the plugin documentation |
Security controls for gRPC traffic at the gateway
gRPC traffic through APISIX touches several trust boundaries at once: the client, the gateway, the upstream service and the control plane that holds routes and protos. The cards below cover the controls that connect those boundaries, and each one names the setting or decision to confirm before the gateway goes live.
TLS to grpcs backends
Upstreams that use grpcs need the gateway to verify the backend certificate, not just encrypt the connection. Set verify: true on the upstream TLS block only after the trusted CA chain is in place, because APISIX 3.19.0 honours that setting for grpcs upstreams and will reject untrusted certificates that earlier releases tolerated. Check the trust store used by each route, especially for internal CAs.
Trusted CA management
APISIX 3.12.0 set ssl_trusted_certificate to the system store by default, so internal backend CAs must be added deliberately rather than assumed. Decide who owns the CA bundle, how rotation reaches every gateway node, and how a CA change is tested on a staging upstream before production traffic depends on it.
Authentication for gRPC methods
Attach key-auth or jwt-auth to the route that serves the gRPC service so requests are authenticated before they reach the upstream. For identity provider flows, the openid-connect plugin supports token introspection and client credentials. Confirm with your architecture team that the gRPC client can send the credential as metadata the plugin reads, and test it with a real client rather than only with curl.
Protecting the Admin API
The Admin API holds routes, consumers, credentials and uploaded protobuf definitions, so anyone who reaches it can change how gRPC methods are exposed. Keep the Admin API (port 9180 in traditional mode) on a private network, restrict access by source address, and rotate the Admin API key. Confirm which control plane component reaches etcd and whether the same key protects every environment.
Rate limits per consumer or method
Apply rate limits keyed by consumer where the caller is identified, so one client cannot starve shared backends. Where callers share a credential, key limits on the route or on a header that identifies the RPC method. Test limits with streaming calls too, since one long-lived stream can hold resources without sending many requests.
Logging and header trust
Log the gRPC service and method names from the request path, but keep request bodies, metadata values and tokens out of access logs, since protobuf payloads often hold personal data. Also decide which incoming forwarding headers the gateway trusts, because a client that sets them directly can spoof its source address or identity. Review both settings with your privacy and security owners before go-live.
What a written scope for gRPC proxying should contain
A fixed scope for gRPC proxying should start with an inventory, because the rest of the plan depends on it. DeployOpen would list every gRPC service and method that will pass through APISIX, the upstream each one reaches, and the client types that call it: internal services, mobile or server-side SDKs, and any browser clients that will need gRPC-Web. For each method the scope should record whether it is unary or streaming, since long-lived streams change timeout and connection settings. It should also name the owner of each .proto file and state how protobuf definitions reach the gateway, whether through the native route, the grpc-transcode plugin's protos endpoint, or both. Confirm this inventory with your service owners before anything is configured.
The scope should also fix the security decisions in writing. For TLS, it should state which upstreams use grpcs, which certificate authority signs each backend, and where the trusted certificates come from. This matters for upstream verification: APISIX 3.19.0 honours upstream.tls.verify for grpcs upstreams, so any upstream already set to verify will begin rejecting certificates it does not trust after the upgrade. Identity is the second decision: which consumer or token model applies to each method, where credentials are validated, and how rate limits are keyed per consumer or per method. The scope should then describe the test plan (method-level functional tests, streaming and deadline behavior, certificate failure cases, and load tests against the current path), along with a rollback and cutover plan that keeps the existing route live until the new one passes.
DeployOpen does not publish a price list. A quote follows from the written scope, and most engagements are fixed-scope, so deliverables, timelines and acceptance criteria are agreed in writing before work starts. Ask for the scope to name each deliverable (route configuration as code, plugin settings, test reports, runbook), the environments covered, what the client provides (service owners, test endpoints, certificates, staging capacity) and what is excluded, such as changes to the backend services themselves. Ask for the cutover criteria in writing, including who approves the switch and how long the old path stays available for rollback. Any timeline in a quote should trace back to these listed items, so that changes to scope are visible as changes to price and schedule.
