Network Requirements
Before you deploy ScalarDB, you typically need to configure firewall rules so that the required network traffic between clients, ScalarDB components, and other Scalar products is allowed. This page lists the connections that you need to allow, including the direction, default port, and use case of each connection, organized by ScalarDB Cluster feature.
The port numbers in the following tables are the default values. If you have changed the default ports in your configuration, use your custom port numbers instead when you configure firewall rules.
ScalarDB Core–related connections
If you're embedding ScalarDB Core as a library in your application, rather than deploying ScalarDB Cluster, you must allow the following connections.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| Client application | Backend databases | Depends on database | Reading/writing requests, including transaction metadata in the Coordinator table |
For more details about the Coordinator table, see Consensus Commit Protocol.
ScalarDB Cluster–related connections
If you're deploying ScalarDB Cluster, you must allow the following connections.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| Client (user applications) | ScalarDB Cluster Node | 60053/TCP | Executing transactions |
| ScalarDB Cluster Node | ScalarDB Cluster Node | 60053/TCP | Routing transaction requests in the cluster internally |
| Scalar Admin for Kubernetes | ScalarDB Cluster Node | 60053/TCP | Executing pause/unpause requests for backup operations |
| Scalar Admin for Kubernetes | Kubernetes API server | 443/TCP | Getting pod, service, and deployment information |
| Client (monitoring tools) | ScalarDB Cluster Node | 9080/TCP | Scraping metrics of ScalarDB Cluster Node |
| ScalarDB Cluster Node | Backend databases | Depends on database | Reading/writing requests to backend databases |
| ScalarDB Cluster Node | Kubernetes API server | 443/TCP | Watching the Endpoints resource to discover cluster nodes |
| Client (direct-kubernetes mode) | Kubernetes API server | 443/TCP | Resolving the cluster node IP addresses to connect to |
| ScalarDB Cluster Node | Cluster DNS (Kubernetes) | 53/UDP, 53/TCP | Resolving hostname through DNS |
You can change these default ports by setting the following properties:
scalar.db.cluster.node.port: the Administrative API, Transaction API, SQL API, and administrator service (default:60053)scalar.db.graphql.port: the GraphQL interface (default:8080)scalar.db.cluster.node.prometheus_exporter_port: metrics (default:9080)
If you configure scalar.db.cluster.node.admin.port to run the administrator service (pause, unpause, and checkPaused) on a dedicated port, that port must also be accessible. In this case, only the administrator service runs on that port, and scalar.db.cluster.node.port must remain accessible for the other gRPC APIs.
Authentication and authorization–related connections
If you use OIDC-based JWT access tokens for authentication, you must allow the following connection.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| ScalarDB Cluster Node | OIDC IdP | Depends on IdP | Fetching the OpenID provider metadata and the JWK Set to verify a JWT access token |
For more details, see Control User Access via OIDC-Based JWT Access Tokens.
Encryption-related connections
If you encrypt column values, you must allow the following connections, depending on the encryption key storage type you use.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| ScalarDB Cluster Node | HashiCorp Vault | Depends on vault.address | Encrypting a column value before writing it (type=vault) |
| ScalarDB Cluster Node | Kubernetes API server | 443/TCP | Reading/writing a data encryption key stored as a Kubernetes secret (type=self) |
For more details, see Encrypt Data at Rest.
GraphQL interface–related connections
If you use the GraphQL interface, you must allow the following connection.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| Client (user applications) | ScalarDB Cluster Node | 8080/TCP | Executing GraphQL queries |
For more details, see Getting Started with ScalarDB Cluster GraphQL.
OpenTelemetry-related connections
If you export metrics and traces by using OpenTelemetry, you must allow the following connections.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| ScalarDB Cluster Node | OTLP endpoint for metrics (Collector) | Depends on endpoint URL | Exporting metrics of a transaction |
| ScalarDB Cluster Node | OTLP endpoint for traces (Collector) | Depends on endpoint URL | Exporting traces of a transaction |
Remote replication-related connections
If you use remote replication for high availability, you must allow the following connections.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| ScalarDB Cluster Node (primary) | Coordinator database | Depends on database | Writing a transaction state |
| ScalarDB Cluster Node (primary) | Replication database | Depends on database | Writing a transaction log before the prepare phase |
| ScalarDB Cluster Node (backup) | Coordinator database | Depends on database | Checking whether a transaction was committed before applying it |
| ScalarDB Cluster Node (backup) | Replication database | Depends on database | Getting a transaction log and applying it to the backup database |
| ScalarDB Cluster Node (backup) | ScalarDB Cluster Node (backup) | 60054/TCP | Reading a coordinator state cached on another node |
| Client (Replication CLI) | ScalarDB Cluster Node | 60053/TCP | Getting the replication status |
You can change this default port by setting the following property:
scalar.db.cluster.internal.node.port: reading coordinator states cached on other nodes (default:60054). This port only needs to be reachable between cluster nodes and should typically be restricted from client and public networks.
For more details, see Replicate Data for High Availability.
Transaction Coordinator–related connections
If you're deploying the Transaction Coordinator to manage two-phase commit transactions across multiple ScalarDB Cluster instances, you must allow the following connections.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| Client (user applications) | Transaction Coordinator Node | 60055/TCP | Executing transaction management requests |
| Transaction Coordinator Node | Transaction Coordinator Node | 60055/TCP | Routing transaction requests in the Transaction Coordinator cluster internally |
| Transaction Coordinator Node | ScalarDB Cluster Node | 60053/TCP | Sending transaction management requests to ScalarDB Cluster Node (participants) |
| Transaction Coordinator Node | Backend databases | Depends on database | Reading/writing transaction metadata in the coordinator table |
| Transaction Coordinator Node | Kubernetes API server | 443/TCP | Watching the Endpoints resource to discover Transaction Coordinator Nodes |
| Scalar Admin for Kubernetes | Transaction Coordinator Node | 60055/TCP | Executing pause/unpause requests for backup operations |
| Client (monitoring tools) | Transaction Coordinator Node | 9080/TCP | Scraping metrics of Transaction Coordinator Node |
| Transaction Coordinator Node | Cluster DNS (Kubernetes) | 53/UDP, 53/TCP | Resolving hostname through DNS |
You can change these default ports by setting the following properties:
scalar.db.cluster.transaction_coordinator.port: the Transaction API (default:60055)scalar.db.cluster.transaction_coordinator.prometheus_exporter_port: metrics (default:9080)
The Transaction Coordinator nodes communicate with each other by using the port specified by scalar.db.cluster.transaction_coordinator.port, which is the same port that clients use. Therefore, this port can't be restricted to communication between Transaction Coordinator nodes only.
If you configure scalar.db.cluster.transaction_coordinator.admin.port to run the administrator service (pause, unpause, and checkPaused) on a dedicated port, that port must also be accessible. In this case, only the administrator service runs on that port, and scalar.db.cluster.transaction_coordinator.port must remain accessible for the Transaction API.
Deprecated – Envoy-related connections for Transaction Coordinator
Using Envoy in front of ScalarDB Cluster has been deprecated for performance reasons.
If you use Envoy in front of ScalarDB Cluster, you must allow the same connections described in Envoy-related connections instead of the connections from the client to ScalarDB Cluster Node in ScalarDB Cluster–related connections.
If you also use Envoy in front of ScalarDB Cluster for Transaction Coordinator participant requests, you must allow the following connection instead of the connection from Transaction Coordinator Node to ScalarDB Cluster Node in the previous table.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| Transaction Coordinator Node | Envoy (for ScalarDB Cluster) | 60053/TCP | Sending transaction management requests to ScalarDB Cluster Node (participants) |
Vector search interface–related connections
If you use the vector search interface for embeddings, you must allow the following connections.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| ScalarDB Cluster Node | Embedding model providers | Depends on providers | Generating an embedding vector for a given text |
| ScalarDB Cluster Node | Vector stores | Depends on stores | Reading/writing vector data |
For more details, see Getting Started with ScalarDB Cluster for Vector Search.
ScalarDB Analytics–related connections
If you use ScalarDB Analytics, you must allow the following connections.
| From | To | Port (default) | Use case example |
|---|---|---|---|
| Client (user applications) | ScalarDB Analytics catalog service | 11051/TCP | Querying catalog metadata |
| Client (user applications) | ScalarDB Analytics metering service | 11052/TCP | Reporting usage metering data |
The port that Apache Spark uses for ScalarDB Analytics depends on how you deploy your Spark cluster. For details about which ports to allow, see your Spark service provider's documentation.