Mutual TLS between Control Plane and Data Plane
Securing the communication channel between the Control Plane (CP) and Data Plane (DP) is fundamental to the integrity of API7 Gateway. Configuration changes, policy updates, and metrics reporting travel through this channel. Data Plane deployments generated by the Dashboard use mutual TLS (mTLS) on DP Manager port 7943. This connection encrypts traffic, requires a Data Plane client certificate, and validates the server certificate against the configured CA.
The DP Manager also accepts HTTP connections on port 7900 for compatibility. These connections use an instance token for authentication but are not encrypted. For production deployments, use the mTLS listener and restrict port 7900 to trusted networks with firewall rules or network policies. Never expose port 7900 to the public internet.
The mTLS path uses a Public Key Infrastructure (PKI) model to issue and verify deployment-specific certificates.
How mTLS Works in API7
Mutual TLS extends the standard TLS protocol by requiring both the client and the server to present and validate a certificate. In the context of API7, the Data Plane acts as the client initiating the connection, and the Control Plane acts as the server.
The process follows a standard PKI trust model:
- Trust Anchor: The Control Plane maintains a unique, automatically generated Certificate Authority (CA). This CA serves as the single root of trust for that specific API7 deployment.
- Certificate Issuance: The Control Plane uses its private CA to issue unique certificates for itself (server certificate) and for each Data Plane node (client certificates).
- Handshake and Verification: When a Data Plane node attempts to connect to the Control Plane, it presents its client certificate. The Control Plane verifies that the certificate was issued by its own trusted CA. Simultaneously, the Data Plane verifies the Control Plane's server certificate against the same CA.
On port 7943, each side checks the other side's certificate during the TLS handshake. The DP Manager rejects clients that do not present a certificate issued by its trusted CA, and the Data Plane rejects server certificates not issued by its configured CA. Protect the CA private key and Data Plane endpoint configuration as sensitive deployment material.
CA and Certificate Management
API7 is designed to make certificate management as automated and secure as possible.
Automatic CA Generation
On its initial startup, the API7 Control Plane checks the database for an existing CA. If no CA is found, it automatically generates a new root CA. This CA is unique to each customer's deployment, ensuring that certificates from one customer's environment cannot be trusted in another. The Control Plane then uses this CA to immediately issue the necessary server and client certificates for establishing secure communication.
Certificate Lifetime
When you install a new Data Plane node, you can specify the certificate validity period based on your organizational security policies. API7 offers the following predefined options:
| Validity Period | Use Case |
|---|---|
| 1 year | High-security environments requiring frequent certificate rotation |
| 2 years | Balanced approach with regular rotation cycles |
| 3 years | Standard enterprise deployments |
| 5 years | Long-lived production environments |
| 10 years | Default; suitable for stable, low-rotation deployments |
By default, new Data Plane nodes are issued certificates with a 10-year validity period. However, you can select a shorter validity period during the Data Plane installation process to enforce more frequent certificate rotation and align with your security compliance requirements.
Certificate Rotation
While certificate generation is automatic, the rotation process is currently a manual operation. Administrators are responsible for tracking certificate expiration and initiating the rotation process when required by their security policies or upon a potential compromise.
Deployment Flexibility
API7 offers flexibility in how Data Plane nodes are deployed. Each Data Plane node can be provisioned with its own unique certificate signed by the Control Plane's CA. Alternatively, for simpler deployment scenarios, multiple Data Plane nodes can share the same client certificate.
Deployment and Configuration
When you generate a Data Plane deployment from the Dashboard, the configuration connects to port 7943 and provisions the required CA and client certificates. This is the normal generated deployment path, but it is not the DP Manager's only listener.
Port 7900 accepts HTTP connections authenticated with an instance token for compatibility. Limit reachability to this port even when all current Data Planes use mTLS.
Verifying mTLS Configuration
Verify that the Data Plane connection endpoint uses https on port 7943 and that the generated CA, client certificate, and client key are installed. A healthy status confirms connectivity, but does not by itself prove that the connection uses mTLS because port 7900 can also serve connected Data Planes.
- Successful Connection: If a Data Plane configured for port
7943appears healthy and connected in the Dashboard, the mTLS connection is established. - Failed Connection: If the mTLS configuration is incorrect, for example because a certificate is missing or invalid, the Data Plane cannot connect to port
7943to fetch configuration. A separately configured connection to port7900is not evidence that mTLS works.
Troubleshooting
The most common issue encountered with CP-DP communication is related to network connectivity, not the mTLS configuration itself. If a Data Plane node fails to connect, check the following:
- Network Reachability: Ensure there is a clear network path between the Data Plane node and the Control Plane on the required HTTPS port.
- Firewall Rules: Verify that no firewalls, security groups, or network policies are blocking traffic between the CP and DP.
- DNS Resolution: Confirm that the Data Plane node can correctly resolve the hostname of the Control Plane.
Performance Considerations
The mTLS mechanism used for securing the CP-DP channel has no performance impact on the API traffic processed by the Data Plane. This secure channel is used exclusively for management tasks, such as the Control Plane pushing configuration updates to the Data Plane and the Data Plane reporting metrics back to the Control Plane. All client-facing API requests are handled by a separate, highly optimized data path that is not involved in this mTLS handshake.