OAP Endpoints for Agents
Which OAP ports this chart opens, how to open more (Zipkin, PromQL, LogQL, TraceQL, self-telemetry), and what agents, swctl and Grafana should point at.
One map drives everything
chart/skywalking/templates/oap-svc.yaml turns every key in oap.ports into a Service port:
ports:
{{- range $key, $value := .Values.oap.ports }}
- port: {{ $value }}
name: {{ $key }}
{{- end }}
oap-deployment.yaml ranges over the same map for containerPort. So adding a key to oap.ports is how you expose a port — there is no separate switch. The Service has no targetPort, so the Service port and the container port are always the same number.
The Service is named <fullname>-oap, type ClusterIP by default. The chart is named skywalking-helm, so helm install skywalking ... renders skywalking-skywalking-helm-oap; add --set fullnameOverride=skywalking (what the e2e tests do) to get a plain skywalking-oap:
helm dep up chart/skywalking
helm template skywalking chart/skywalking \
--set oap.image.tag=11.0.0 \
--set oap.storageType=banyandb \
--set elasticsearch.enabled=false \
--set banyandb.enabled=true \
--set banyandb.image.tag=0.11.0 \
--set ui.image.tag=horizon-1.0.0 \
-s templates/oap-svc.yaml
The ports
| Key | Default | Serves | In oap.ports by default |
Needs OAP env too |
|---|---|---|---|---|
grpc |
11800 |
Native agent protocol (traces, JVM/meters, profiling, logs, events). Every other gRPC receiver — OTLP, Envoy ALS, Rover eBPF, Satellite forwarding — shares it, because SW_RECEIVER_GRPC_PORT defaults to 0 (fall back to the core gRPC server) |
yes | no |
rest |
12800 |
GraphQL query API at /graphql (Horizon’s oap.queryUrl, swctl), unless query is set. HTTP receivers share it for the same reason (SW_RECEIVER_SHARING_REST_PORT:0). All three pod probes tcpSocket this port |
yes | no |
receiver-grpc |
11811 in the commented example |
The gRPC receivers moved off grpc — see Separate the receiver and query ports. Satellite forwards here when it is set |
no | no — the chart sets SW_RECEIVER_GRPC_PORT |
receiver-rest |
12811 in the commented example |
The HTTP receivers moved off rest |
no | no — the chart sets SW_RECEIVER_SHARING_REST_PORT |
query |
12810 in the commented example |
The GraphQL query API, the AI agent conversation API and /status/config/ttl, moved off rest. Horizon’s oap.queryUrl follows it. Needs OAP 11.2.0 or later |
no | no — the chart sets SW_QUERY_SERVER_REST_PORT |
admin |
17128 |
admin-server: /status/*, /debugging/*, inspect, dsl-debugging, runtime-rule, and the ui-management template store Horizon uses when ui.config.templates.mode is live. Wired into Horizon as oap.adminUrl |
yes | no |
zipkin-receiver |
9411 |
Zipkin span ingestion, POST /api/v2/spans |
no | no — the chart sets SW_RECEIVER_ZIPKIN=default and SW_RECEIVER_ZIPKIN_REST_PORT for you |
zipkin-query |
9412 |
Zipkin query API under /zipkin (Zipkin-Lens compatible). Also makes the chart write Horizon’s oap.zipkinUrl |
no | no — the chart sets SW_QUERY_ZIPKIN=default and SW_QUERY_ZIPKIN_REST_PORT |
promql |
9090 |
Prometheus-compatible query API (Grafana datasource) | no | no — the promql module is on by default in OAP 11 |
logql |
3100 |
Loki-compatible log query API | no | no — the logql module is on by default in OAP 11 |
traceql |
3200 |
Tempo-compatible trace query API | no | yes — SW_TRACEQL defaults to empty (module off) |
metrics |
1234 |
OAP self-telemetry, Prometheus exposition for scraping | no | no — SW_TELEMETRY defaults to prometheus on 1234 |
zabbix |
10051 |
Zabbix receiver (the example line in values.yaml) |
no | yes — SW_RECEIVER_ZABBIX defaults to empty |
“In oap.ports by default” means the chart publishes the Service/container port. The last column is about OAP itself: a port that is published but whose module is off answers nothing.
admin: 17128 is required for OAP 11 and is what Horizon’s admin calls go to. Set it to null on any OAP 10.x release: admin-server first appears in OAP 11, and on 10.x port 17128 is the AI-pipeline URI-recognition server.
Opening more ports
Uncomment the lines already present in values.yaml, or pass them on the command line:
helm install skywalking oci://docker.io/apache/skywalking-helm \
--version 5.0.0 \
--set oap.image.tag=11.0.0 \
--set oap.storageType=banyandb \
--set elasticsearch.enabled=false \
--set banyandb.enabled=true \
--set banyandb.image.tag=0.11.0 \
--set ui.image.tag=horizon-1.0.0 \
--set oap.ports.zipkin-receiver=9411 \
--set oap.ports.zipkin-query=9412
For a module that is off in OAP, add the port and the env — oap.env values are rendered quoted, so booleans are safe:
oap:
ports:
grpc: 11800
rest: 12800
admin: 17128
traceql: 3200
metrics: 1234
env:
SW_TRACEQL: default
SW_TRACEQL_ENABLE_DATASOURCE_SKYWALKING: true
Port names are Kubernetes port names: lowercase, [a-z0-9-], 15 characters max (zipkin-receiver is exactly 15).
Do not renumber grpc / rest / admin on their own
The chart feeds oap.ports to Kubernetes, not to OAP — for these three it never sets the matching SW_* variable. OAP keeps binding SW_CORE_GRPC_PORT:11800, SW_CORE_REST_PORT:12800 and SW_ADMIN_SERVER_PORT:17128, so changing only the value gives you a Service pointing at a closed port. If you must move one, change all of it:
oap:
ports:
rest: 12801
env:
SW_CORE_REST_PORT: 12801
livenessProbe:
tcpSocket: { port: 12801 }
initialDelaySeconds: 5
periodSeconds: 10
readinessProbe:
tcpSocket: { port: 12801 }
initialDelaySeconds: 5
periodSeconds: 10
startupProbe:
tcpSocket: { port: 12801 }
failureThreshold: 30
periodSeconds: 10
The default probes hardcode 12800; leaving them behind makes the pod restart-loop. Horizon needs no change either way — the UI ConfigMap renders oap.queryUrl / oap.adminUrl from oap.ports.rest (or oap.ports.query when set) / oap.ports.admin. zipkin-receiver and zipkin-query have no such problem — the chart derives their env from the value.
Separate the receiver and query ports
By default grpc and rest carry both the agent and the query traffic: agents report on the same
ports that the UI queries, and grpc also carries the cluster traffic between OAP nodes.
Three keys split them, so each port can be published, firewalled and given TLS on its own:
oap:
ports:
grpc: 11800
rest: 12800
admin: 17128
receiver-grpc: 11811 # agents, Envoy, OTLP gRPC, Satellite
receiver-rest: 12811 # browser SDK, HTTP agents, OTLP HTTP
query: 12810 # GraphQL, AI agent conversations, /status/config/ttl
For each key that is set, the chart publishes the port and sets the OAP variable that starts the
server (SW_RECEIVER_GRPC_PORT, SW_RECEIVER_SHARING_REST_PORT, SW_QUERY_SERVER_REST_PORT). It
also points its own clients at the new ports: Horizon’s oap.queryUrl uses query, and Satellite
forwards to receiver-grpc. With all three set, no agent or query traffic is left on grpc and
rest: grpc carries the cluster traffic between OAP nodes, and rest the probes, which keep
checking 12800. The keys are independent; set only the ones you need.
receiver-grpc and receiver-rest work on every OAP release this chart supports. query needs OAP
11.2.0 or later: an older OAP ignores the variable and keeps GraphQL on 12800, while Horizon would
query the closed query port.
Repoint the clients outside the chart yourself: agents to receiver-grpc, browser and other HTTP
reporters to receiver-rest, and swctl --base-url or any other GraphQL client to query.
What to point at what
Assuming release skywalking in namespace skywalking, installed with --set fullnameOverride=skywalking so the Service is skywalking-oap. Without that override the name is skywalking-skywalking-helm-oap — substitute it everywhere below.
| Client | Address |
|---|---|
| Java / Go / Python / Node.js / Rust / nginx-lua agents | skywalking-oap.skywalking.svc:11800 (gRPC, no scheme) |
| OTLP, Envoy ALS, Rover eBPF | the same :11800 |
| Browser and other HTTP reporters | http://skywalking-oap.skywalking.svc:12800 |
swctl |
--base-url=http://skywalking-oap.skywalking.svc:12800/graphql |
| Horizon UI | wired by the chart: query :12800, admin :17128 |
| Zipkin senders | http://skywalking-oap.skywalking.svc:9411/api/v2/spans |
| Grafana (Prometheus / Loki datasource) | http://skywalking-oap.skywalking.svc:9090, :3100 |
| Prometheus scrape of OAP itself | skywalking-oap.skywalking.svc:1234 |
Java agent example:
-Dskywalking.collector.backend_service=skywalking-oap.skywalking.svc:11800
Horizon does not proxy /graphql to OAP, so anything that used to query through the UI must talk to the OAP Service directly on 12800.
If Satellite is enabled, agents point at the Satellite Service on 11800 instead and Satellite forwards to OAP.
Reaching OAP from outside the cluster
The chart ships no Ingress for OAP — only the UI has one (see UI Service and Ingress). Options:
# one laptop, temporary
kubectl port-forward -n skywalking svc/skywalking-oap 12800:12800
# agents outside the cluster
oap:
service:
type: LoadBalancer
annotations:
service.beta.kubernetes.io/aws-load-balancer-type: nlb
oap.service.type accepts any Service type (ClusterIP, NodePort, LoadBalancer) and oap.service.annotations is passed straight through to the Service metadata. The agent protocol on 11800 is gRPC over HTTP/2, so an L7 HTTP ingress will not do — use an L4 / NLB Service or a gRPC-aware gateway.
A public OAP Service publishes every key in oap.ports, and admin: 17128 is one of them by default — it serves /status/*, /debugging/*, inspect and the runtime-rule write APIs. Front the public address with something that forwards only 11800 / 12800 (or only the receiver ports, when separated) rather than dropping admin from oap.ports: the UI ConfigMap still renders oap.adminUrl as :17128, so removing the port breaks Horizon. See TLS before putting any of these on the internet.
Related
- Configure OAP —
oap.env,oap.config, dynamic configuration - Satellite Gateway
- skywalking Chart values
- OAP Configuration Vocabulary — every
SW_*variable and its default