Deploy an RPM Data Plane from a Docker Script

Use this guide after you install api7-gateway via RPM and need to connect it to the control plane. 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 RPM data plane configuration file, config.yaml. See Deploy with the Offline RPM Bundle for the RPM installation workflow.

Get the Docker Script from the Dashboard

In the Dashboard, go to your gateway group, click Add Instance, select 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.

Map Environment Variables to RPM Configuration

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

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

Edit the Gateway Configuration

Edit the gateway configuration file at /usr/local/apisix/conf/config.yaml. Apply the values from the generated Docker command:

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    host:
      - https://<CP_HOST>:7943
    tls:
      cert: /usr/local/apisix/conf/cert/api7ee.crt
      key: /usr/local/apisix/conf/cert/api7ee.key
      # sni: <API7_DP_MANAGER_SNI>
apisix:
  ssl:
    ssl_trusted_certificate: /usr/local/apisix/conf/cert/api7ee_ca.crt

If the Docker script includes API7_DP_MANAGER_SNI, remove the comment marker from sni and set that value.

Start and Verify the Gateway

Start the gateway service and confirm that it is active:

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.

Troubleshooting

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.

Dashboard metrics require a Prometheus service, which is not included in the bundle. Install it and point the dp-manager at it. See Install Prometheus 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.

To troubleshoot mTLS, check /usr/local/apisix/logs/error.log. certificate verify failed or 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.