Kubernetes agent gateway

Overview

On Kubernetes, the DeviceQuest Helm chart runs the agent gateway inside the control plane. By default its gRPC port is reachable only inside the cluster. Set agentGateway.external.enabled=true and the chart publishes the gateway through your existing ingress host on port 443, switches it to token authentication, and turns on the one-command agent install on Admin → Enroll Agent. Agents then need only outbound HTTPS to your DeviceQuest host.

This page is for the operator who installs DeviceQuest with Helm.

How it works

Agent host ──HTTPS 443──▶ ingress (TLS) ──GRPCS──▶ <release>-agent-gateway:50051 ──▶ control plane
            /api/v1/agent/install.sh|ps1, /api/v1/agent/download/<platform>  (install and download)
            /devicequest.gateway.v1.AgentGateway                              (agent gateway, gRPC)

• The agent checks the ingress certificate with the host’s trust store, or with your CA file.
• The ingress forwards gRPC to the gateway over TLS (backend-protocol: GRPCS), using the certificate the chart generates for the gateway.
• Each agent authenticates with its own token, issued at enrollment. No client certificates are needed.
• The control plane serves the install scripts and agent binaries itself, gated by the one-time bootstrap credential in the URL.

Requirements

If one is missing, helm upgrade stops with a message such as agentGateway.external.enabled requires ingress.tlsSecretName: nginx carries gRPC over HTTP/2, which needs TLS.

Enable external agents

1. Add the setting to your Helm install:

   helm upgrade --install devicequest oci://harbor.cyberquest.cloud/helm/devicequest --version <version> \
     --namespace <ns> \
     --set-string ingress.host=dq.example.com \
     --set-string ingress.tlsSecretName=<tls-secret> \
     --set agentGateway.external.enabled=true \
     --reuse-values
   

   Or in a values file:

   agentGateway:
     external:
       enabled: true
       # Extra annotations for the agent gateway Ingress, if your controller needs them.
       annotations: {}
   

2. Wait for the control plane to restart.

3. Open Admin → Enroll Agent. The Gateway field now reads dq.example.com:443 and Set by this deployment (agentGateway.external)., and step 4 shows a one-line install command.

What the chart changes

In saas mode the gateway always runs with TLS. Without agentGateway.external.enabled, it uses mutual TLS for agents inside the cluster. Add extra DNS names to the generated gateway certificate with agentGateway.tls.extraDnsNames.

Helm values

One-command install requirements

The one-command install is on when all of these are true. Otherwise the Enroll Agent page shows the manual install script and the note One-command installs are off for this deployment.

• The control plane runs the agent gateway.
• DEVICEQUEST_PUBLIC_URL is an https:// URL. The chart sets it from ingress.host.
• DEVICEQUEST_AGENT_GATEWAY_ADVERTISE_ADDR is set. The chart sets it when agentGateway.external.enabled=true.
• The control-plane image contains the agent builds and their manifest.json in DEVICEQUEST_AGENT_ARTIFACT_DIR. The published images include linux-amd64, linux-arm64 and windows-amd64.

Install endpoints

• The token must be an active, unexpired bootstrap credential. Otherwise the response is 404 with install command not found or expired; ask your admin for a new one.
• When downloads are off, the response is 503 with agent downloads are not configured on this deployment.
• The control plane allows 120 requests a minute per connecting address. Behind the ingress, all requests come from the ingress controller, so every host shares that budget, and each install makes 2 requests. Plan rollouts at up to about 60 hosts a minute; on 429, wait 60 seconds and retry (the response carries Retry-After: 60).
• Responses are sent with Cache-Control: no-store.

Private certificate authority

If the ingress certificate comes from a private CA, agents must trust that CA:

• Linux: tick The server certificate is from a private CA (I have its ca.pem on the host) on the Enroll Agent page. The command passes ca.pem to curl and the installer stores it as /etc/devicequest-agent/ca.pem for the agent. See Install on Linux.
• Windows: import the CA into the computer’s Trusted Root Certification Authorities store before you run the install command.

Network requirements

No inbound connection to the agent host is needed.

Verify

1. On a test host, run the one-command install from Admin → Enroll Agent.
2. On Linux, run sudo journalctl -u devicequest-agent -f and look for enrollment successful.
3. Open Admin → Host Agents. The agent is listed as online.

Related pages

• Agent overview
• Install on Linux
• Install on Windows
• CLI reference
• Updates, revoke and uninstall