Deploy an RPM Data Plane Using the Dashboard's Docker Script

The Dashboard's Add Instance flow generates Docker, Docker Compose, and Helm scripts, but does not yet generate an RPM script. This guide takes the connection parameters from the generated Docker script and applies the equivalent settings to the api7-gateway config.yaml. That connects the RPM data plane to the control plane.

Audience: operators who installed api7-gateway via RPM (see Deploy with the Offline RPM Bundle) and need to connect it to the control plane.

1. Get the Docker Script from the Dashboard

In the Dashboard, go to your Gateway Group → Add Instance → Docker and copy the generated docker run command. It carries every connection parameter as environment variables:

docker run -d \
  -e API7_DP_MANAGER_ENDPOINTS='["https://<CP_HOST>:7943"]' \
  -e API7_GATEWAY_GROUP_SHORT_ID=default \
  -e API7_DP_MANAGER_CERT="-----BEGIN CERTIFICATE-----
  ...client certificate...
  -----END CERTIFICATE-----" \
  -e API7_DP_MANAGER_KEY="-----BEGIN PRIVATE KEY-----
  ...client private key...
  -----END PRIVATE KEY-----" \
  -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
  ...CA certificate...
  -----END CERTIFICATE-----" \
  -p 9080:9080 -p 9443:9443 \
  api7/api7-ee-3-gateway:<version>

You only need the five API7_* environment-variable values.

2. Environment Variable → RPM config.yaml Mapping

Docker environment variable	Location in the RPM config.yaml	Notes
API7_DP_MANAGER_ENDPOINTS	deployment.etcd.host	JSON array → YAML list
API7_DP_MANAGER_CERT	Write to conf/cert/api7ee.crt; set the path in deployment.etcd.tls.cert	Client certificate
API7_DP_MANAGER_KEY	Write to conf/cert/api7ee.key; set the path in deployment.etcd.tls.key	Client private key
API7_CONTROL_PLANE_CA	Write to conf/cert/api7ee_ca.crt; set the path in apisix.ssl.ssl_trusted_certificate	Verifies the dp-manager server certificate
API7_DP_MANAGER_SNI (optional)	deployment.etcd.tls.sni	Omit if the Docker script did not set it; can be omitted when the endpoint is an IP that is present in the server certificate's SAN
API7_GATEWAY_GROUP_SHORT_ID	Not needed in config.yaml	The gateway-group identity is carried by the client certificate

3. Write the Certificate Files

Write the three PEM blocks to the gateway's cert directory (strip any extra leading whitespace that the Docker command may have added per line):

sudo install -d -m 0755 /usr/local/apisix/conf/cert

sudo tee /usr/local/apisix/conf/cert/api7ee.crt > /dev/null <<'EOF'
-----BEGIN CERTIFICATE-----
...API7_DP_MANAGER_CERT content...
-----END CERTIFICATE-----
EOF

sudo tee /usr/local/apisix/conf/cert/api7ee.key > /dev/null <<'EOF'
-----BEGIN PRIVATE KEY-----
...API7_DP_MANAGER_KEY content...
-----END PRIVATE KEY-----
EOF

sudo tee /usr/local/apisix/conf/cert/api7ee_ca.crt > /dev/null <<'EOF'
-----BEGIN CERTIFICATE-----
...API7_CONTROL_PLANE_CA content...
-----END CERTIFICATE-----
EOF

4. Edit config.yaml

Edit /usr/local/apisix/conf/config.yaml, replacing the endpoint with your API7_DP_MANAGER_ENDPOINTS value:

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    host:
      - https://<CP_HOST>:7943                   # API7_DP_MANAGER_ENDPOINTS
    tls:
      cert: /usr/local/apisix/conf/cert/api7ee.crt   # API7_DP_MANAGER_CERT
      key: /usr/local/apisix/conf/cert/api7ee.key    # API7_DP_MANAGER_KEY
      # sni: <API7_DP_MANAGER_SNI>                    # only if the Docker script set this variable
apisix:
  ssl:
    ssl_trusted_certificate: /usr/local/apisix/conf/cert/api7ee_ca.crt   # API7_CONTROL_PLANE_CA

5. Start and Verify

sudo systemctl enable --now api7-gateway
systemctl is-active api7-gateway

Confirm the data-plane ports are listening:

ss -ltn | grep -E ':9080|:9443'

Back in the Dashboard, open the Instances list of the gateway group; the instance should appear shortly and turn Healthy.

note

If the instance never appears and the log shows requires a sufficient license, the control plane has no License uploaded yet (Dashboard → Settings → License). This is a control-plane prerequisite, not a data-plane configuration problem.

note

Dashboard metrics require a Prometheus service, which is not included in the bundle — you must install it and point the dp-manager at it. See Install Prometheus (required for metrics) in the offline RPM guide. Until then a connected gateway logs agent.lua:544: upload metrics block failed, status: 500; this is expected when Prometheus is absent, and the instance is still Healthy with traffic unaffected.

tip

To troubleshoot mTLS, check /usr/local/apisix/logs/error.log. certificate verify failed / handshake failed usually means a CA or SNI mismatch. If the endpoint uses a hostname, make sure it is in the dp-manager server certificate's SAN, or set the sni from API7_DP_MANAGER_SNI.