You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "deekshith-hadil (via GitHub)" <gi...@apache.org> on 2026/07/14 01:51:02 UTC
[I] Question: ApisixRoute CRD stream backend lacks scheme: tls — is Admin API safe to use alongside CRDs? [apisix-ingress-controller]
deekshith-hadil opened a new issue, #2803:
URL: https://github.com/apache/apisix-ingress-controller/issues/2803
## Summary
We use APISIX Ingress Controller (v2.x) with CRDs for HTTP routes but need the Admin API for stream routes that require `upstream.scheme: tls`. The [upgrade guide](https://apisix.apache.org/docs/ingress-controller/upgrade-guide/#controller-only-configuration-source) states that manual Admin API changes will be overwritten on the next full sync. We need clarity on whether this applies to stream routes.
## Our Setup
- APISIX 3.x (OSS) with Ingress Controller 2.x
- **HTTP routes:** Managed entirely via `ApisixRoute` CRD — works fine
- **Inbound stream routes (plain TCP, TLS termination):** Managed via `ApisixRoute` CRD — works fine
- **Outbound stream routes (APISIX initiates TLS to upstream):** Requires `upstream.scheme: tls` — **only possible via Admin API**
## Why We Need the Admin API for Stream Routes
The `ApisixRoute` CRD's stream backend has no `scheme` field:
```yaml
# This is all the CRD allows for stream backends
spec:
stream:
- name: my-route
protocol: TCP
match:
ingressPort: 8000
backend:
serviceName: my-service
servicePort: 6000
```
There is no way to specify `scheme: tls` here. We also tried:
- `ApisixUpstream` CRD with `scheme: https` → ignored for stream routes (only applies to HTTP)
- `ApisixUpstream` CRD with `scheme: tls` → rejected by CRD validation (not an allowed value)
- Gateway API `BackendTLSPolicy` → not supported by APISIX Ingress Controller
The only working approach:
```bash
curl -X PUT http://admin:9180/apisix/admin/stream_routes/my-route \
-H "X-API-KEY: $KEY" \
-d '{
"server_port": 8000,
"upstream": {
"type": "roundrobin",
"scheme": "tls",
"nodes": {"upstream-server:6000": 1}
}
}'
```
## Our Concern
The documentation says:
> Starting with APISIX Ingress Controller 2.0.0, the controller is the single source of truth. Manual Admin API changes will be overwritten on the next full sync.
In our testing, stream routes created via Admin API are **not being overwritten** by the ingress controller. But we are unsure if this is guaranteed behaviour or just happens to work today.
## Questions
1. **Will stream routes created via Admin API be overwritten by the ingress controller?** Is the current behaviour (stream routes surviving full sync) intentional and stable, or could it change?
2. **Is there a plan to add `scheme` support to the `ApisixRouteStream` CRD?** This would allow us to configure outbound TLS stream routes declaratively.
3. **Can we safely use Admin API for stream routes alongside CRD-managed HTTP routes in production?**
## Use Case
We use APISIX as a TCP stream proxy. For outbound connections, the upstream server requires TLS. Our clients send plain TCP to APISIX, and APISIX must initiate TLS to the upstream before forwarding the data. This requires `upstream.scheme: tls` on the stream route — which has no CRD equivalent today.
```mermaid
sequenceDiagram
participant Client as TCP Client
participant APISIX as APISIX Gateway (Port 8000)
participant Upstream as Upstream TLS Server (Port 6000)
Client->>APISIX: TCP Connect (plain)
APISIX->>Upstream: TLS Connect
APISIX->>Upstream: TLS ClientHello
Upstream->>APISIX: TLS ServerHello + Certificate
Note over APISIX,Upstream: TLS session established
Client->>APISIX: Data (plain TCP)
APISIX->>Upstream: Data (TLS encrypted)
Upstream->>APISIX: Response (TLS encrypted)
APISIX->>Client: Response (plain TCP)
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Question: ApisixRoute CRD stream backend lacks scheme: tls — is Admin API safe to use alongside CRDs? [apisix-ingress-controller]
Posted by "AlinsRan (via GitHub)" <gi...@apache.org>.
AlinsRan commented on issue #2803:
URL: https://github.com/apache/apisix-ingress-controller/issues/2803#issuecomment-5113408360
Thanks for the detailed write-up — it makes the answer easy to give precisely.
## 1 & 3. Why the Admin API stream routes survive today (and why you should not rely on it)
It is an artifact of the sync implementation, not a guarantee.
With `provider.type: apisix`, the controller syncs through ADC: ADC dumps the current APISIX configuration and diffs it against the configuration the controller owns. When ADC fetches `/apisix/admin/stream_routes`, it only keeps a stream route if it has a `service_id`; a stream route with an inline `upstream` and no service — exactly what your `curl` creates — is dropped during the dump, so it never enters the diff and never gets deleted.
Two consequences:
- Nothing protects that route; it survives only because it is invisible to the diff. Attach it to a service, or let ADC start handling service-less stream routes, and it will be removed on the next full sync.
- With `provider.type: apisix-standalone` this does not apply at all — the controller pushes a full configuration snapshot, so anything not generated from CRDs is dropped.
So: not intentional, not a contract, and not something I would build a production setup on.
## 2. `scheme: tls` for stream routes
The plumbing is already in place; the only blocker is CRD validation.
- `ApisixRoute` stream backends do pick up an `ApisixUpstream` with the same name as the backend Service (`validateHTTPBackend` populates it, `translateApisixRouteStreamBackend` merges it), and its `scheme` reaches the generated upstream.
- Gateway API `TCPRoute` backends take `scheme` from `BackendTrafficPolicy` in the same way.
Both CRDs restrict the field to `http|https|grpc|grpcs`, while APISIX itself accepts `tcp|tls|udp` for L4 upstreams. That is why `scheme: tls` is rejected by the CRD and `scheme: https` is accepted but meaningless at L4 — it is a validation gap, not a data-plane limitation.
The fix is to allow the L4 schemes in those two fields. I will open a PR for it and link it here. After that your case becomes:
```yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
name: my-service # same name as the backend Service
spec:
scheme: tls
```
or, on the Gateway API side, a `BackendTrafficPolicy` with `scheme: tls` targeting the Service used by the `TCPRoute`.
Until that ships, the Admin API workaround will keep working as long as you stay on `provider.type: apisix` and keep the stream route service-less — but treat it as a temporary measure, not a supported configuration.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Question: ApisixRoute CRD stream backend lacks scheme: tls — is Admin API safe to use alongside CRDs? [apisix-ingress-controller]
Posted by "AlinsRan (via GitHub)" <gi...@apache.org>.
AlinsRan commented on issue #2803:
URL: https://github.com/apache/apisix-ingress-controller/issues/2803#issuecomment-5113629084
PR is up: #2830 — it allows `tcp`/`tls`/`udp` in `ApisixUpstream.spec.scheme` and `BackendTrafficPolicy.spec.scheme`, which covers both the ApisixRoute stream path and the Gateway API TCPRoute path.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Question: ApisixRoute CRD stream backend lacks scheme: tls — is Admin API safe to use alongside CRDs? [apisix-ingress-controller]
Posted by "AlinsRan (via GitHub)" <gi...@apache.org>.
AlinsRan closed issue #2803: Question: ApisixRoute CRD stream backend lacks scheme: tls — is Admin API safe to use alongside CRDs?
URL: https://github.com/apache/apisix-ingress-controller/issues/2803
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org