Connect to databases through CQL gateways

CQL gateways provide external access to your database clusters through the CQL native protocol. This enables connections through tools such as Apache Cassandra® drivers.

For optimal gateway performance:

Deploy at least three gateway replicas for high availability.
Configure appropriate resource limits for gateway pods.
Use connection pooling in client applications.

Prerequisites

A running database cluster managed by Mission Control
Access to the Mission Control UI
An Ingress controller installed in your Kubernetes cluster
DNS configuration access

Create an Ingress gateway

Create an Ingress gateway to expose your database cluster externally. An Ingress gateway routes traffic based on domain names through your Kubernetes Ingress controller.

In the Mission Control UI, select your project, and then select your database cluster.
Click Connect, and then click Add Gateway.
In the list of datacenters, select the datacenter you want to expose.
For Connectivity Type, select Ingress.
Enter the number of replicas.

Triple replication is recommended for production deployments to ensure high availability.
For DNS Base Name, enter the gateway domain name, such as dc1.cluster.ingress.example.io.
Click Add Gateway.

Mission Control creates an Ingress resource with the specified domain name. For example:
```
{
  "name": "cql-gateway",
  "type": "Ingress",
  "size": 3,
  "dnsBaseName": "cql.example.com"
}
```
Configure DNS to route traffic to your Ingress controller:
1. Get your Ingress controller’s external IP or hostname:
  
  kubectl get service -n INGRESS_NAMESPACE HAPROXY_SERVICE_NAME
  
  Replace the following:
  
  INGRESS_NAMESPACE: The namespace where your Ingress controller is deployed.
  
  HAPROXY_SERVICE_NAME: The name of the HAProxy service in your Ingress controller. To find it, run kubectl get services -n INGRESS_NAMESPACE and select the HAProxy service.
2. If you aren’t using wildcard DNS, create a DNS A record or CNAME pointing your gateway domain to the Ingress controller.
  
  For example, direct cql.example.com to the external IP or hostname of your Ingress controller:
  
  This step isn’t required when using a wildcard DNS entry, such as *.mc.example.com to your Ingress controller IP. With wildcard DNS, all subdomains automatically resolve to the configured address.
3. Verify DNS resolution:
  
  nslookup DNS_BASE_NAME
  
  Replace DNS_BASE_NAME with your gateway domain name.
4. Test connectivity:
  
  echo | openssl s_client -connect CLUSTER_DOMAIN_NAME:443 -servername HOST_ID
  
  Replace the following:
  
  CLUSTER_DOMAIN_NAME: The domain name of your Ingress controller, which listens on port 443 and routes traffic to the CQL gateway
  
  HOST_ID: The host ID used as the SNI hostname to route the connection to the correct CQL router

Troubleshoot Ingress gateways

If Ingress routing doesn’t work, do the following:

Verify that Mission Control created the Ingress resource:
```
kubectl get ingress -n PROJECT_SLUG
```
Replace PROJECT_SLUG with your project namespace. You can find the project slug in the Mission Control UI breadcrumbs next to the cluster name on the cluster details page.
Check Ingress controller logs:
```
kubectl logs -n INGRESS_NAMESPACE
```
Replace INGRESS_NAMESPACE with the namespace where your Ingress controller is deployed.
Verify that your Ingress controller has TLS passthrough enabled:
```
kubectl get ingress -n INGRESS_NAMESPACE -o=jsonpath='{.items[*].spec.tls}'
```
Replace INGRESS_NAMESPACE with the namespace where your Ingress controller is deployed.
Confirm that your Ingress controller supports TCP services by testing the connection:
```
echo | openssl s_client -connect CLUSTER_DOMAIN_NAME:443 -servername HOST_ID
```
Replace the following:
- CLUSTER_DOMAIN_NAME: The domain name of your Ingress controller, which listens on port 443 and routes traffic to the CQL gateway
- HOST_ID: The host ID used as the SNI hostname to route the connection to the correct CQL router

Connect through a CQL gateway with the Secure Connect Bundle (SCB)

To connect to your database cluster through a CQL gateway, download the SCB for the gateway, and then configure your client application to use it.

About the SCB

To use the SCB effectively, it is important that you understand the following:

The SCB is a zip file that contains information for configuring a secure connection between a client application and a CQL gateway. Specifically, the SCB contains the following:
- config.json: Connection configuration including host, port, datacenter, and keystore passwords
- ca.crt: Certificate Authority certificate for TLS verification
- cert: Client certificate for authentication
- key: Private key for the client certificate
- identity.jks: Java KeyStore containing the client identity
- trustStore.jks: Java TrustStore containing trusted CA certificates
Although the SCB cannot grant access to your database on its own, you should still treat it as you would other secret and sensitive values like passwords and API keys.
Each SCB is associated with one CQL gateway and cannot be used to connect to other gateways or clusters.

If your application needs to connect to multiple gateways, such as for different datacenters, you must download the SCB for each gateway separately, and then define logic in your application code to select the correct SCB for each connection.
Provide the entire SCB zip file in your client application’s connection configuration.

Don’t extract the SCB archive unless you require a specific file or value from within the bundle for a particular integration or configuration. Typically, extraction is only necessary for integrations that don’t include support for connections with the SCB, such as unsupported Cassandra drivers.
SSL encryption for client-to-gateway communication is automatically enabled.

The SCB contains TLS certificates for the CQL gateway. Driver connections using the SCB automatically use TLS for secure communication with the gateway.
You must use the SCB to connect through the CQL gateway.

Classes and options that use the SCB are available in supported Cassandra drivers, cqlsh, and driver-based tools like DataStax Bulk Loader (DSBulk).

If you have configured direct IP routing to your Mission Control installation’s CQL routers or database pods, you can also connect to your database clusters directly. This access requires routing table entries in your network or host network. For direct connections, use traditional cluster connection configuration options, such as contact points, SSL settings, and authentication credentials.
Once downloaded, the SCB never expires. If you no longer need a bundle, delete it from your environment or project.

Download the SCB

In the Mission Control UI, download the SCB for a configured CQL gateway. To connect to multiple gateways, download the SCB for each gateway separately. For more information, see About the SCB.

In the Mission Control UI, navigate to your cluster’s Connect tab.
Click Gateway.
Select the gateway that you want to connect to.
Click Download Secure Connect Bundle.

Connect using the SCB

After you download the SCB, configure your Cassandra driver to connect through the CQL gateway.

CQL gateway connections use the gateway’s SCB along with the same username and password authentication as other database connections. SCB connections aren’t compatible with authentication methods that don’t use username and password authentication, such as DSE Kerberos authentication.

Get your database credentials:
```
kubectl get secret CLUSTER_NAME-superuser -n PROJECT_SLUG -o jsonpath='{.data.username}' | base64 --decode
kubectl get secret CLUSTER_NAME-superuser -n PROJECT_SLUG -o jsonpath='{.data.password}' | base64 --decode
```
Replace the following:
- CLUSTER_NAME: Your cluster name.
- PROJECT_SLUG: Your project namespace. You can find the project slug in the Mission Control UI breadcrumbs next to the cluster name on the cluster details page.
Use the database username and password with the gateway’s SCB in your driver’s connection configuration.

Don’t specify contact points or SSL options when using the SCB. The SCB provides these details automatically.

The exact classes and options to use depend on the driver language. Some drivers refer to the SCB connection as a cloud connection because it was originally designed to connect to Astra DB.

If you are using the gocql driver, you must use gocql-astra instead. gocql-astra includes gocql with added support for SCB connections.

For more information and examples, see the following:
- Your driver’s documentation
- Get started with Cassandra drivers for HCD
- Get started with Cassandra drivers for DSE

Get CQL gateway status and logs

Use the following commands to inspect the health of your CQL gateway pods. In these commands, replace PROJECT_SLUG with your project namespace. You can find the project slug in the Mission Control UI breadcrumbs next to the cluster name on the cluster details page.

Get the status of the CQL gateway pods:

kubectl get pods -l app=cql-gateway -n PROJECT_SLUG

Get CQL gateway logs:

kubectl logs -l app=cql-gateway -n PROJECT_SLUG