Configure TLS between Gremlin client and AGS

This page contains an example that demonstrates how to encrypt the WebSocket connection between your Gremlin client and Aerospike Graph Service. Client-to-AGS TLS protects query data and results as they travel over the network.

Generate certificates

The example includes a script that creates a Certificate Authority (CA) and server certificates for AGS.

1. Navigate to the GremlinClient-to-AGS directory.

   cd GremlinClient-to-AGS

2. Run the certificate generation script.

   ./make-certs.sh

   Example response

   Checking system for openssl command.
   /opt/homebrew/bin/openssl
   Found OpenSSL 3.5.0 8 Apr 2025 (Library: OpenSSL 3.5.0 8 Apr 2025).
   Generating CA key 'security/ca.key'.
   .....+++++++++++++++++++++++++++++++++++++++*...+++++++++++++++++++++++++++++++++++++++*
   Generating self-signed CA cert 'security/ca.crt'.
   Generating server key 'g-tls/server.key'.
   ..+++++++++++++++++++++++++++++++++++++++*...+++++++++++++++++++++++++++++++++++++++*
   Signing server CSR with CA.
   Signing server CERT with CA.
   Certificate request self-signature ok
   subject=C=US, ST=California, L=San Francisco, O=ExampleCorp, OU=DevOps, CN=exampleCluster
   Removing intermediate files
   Files generated:
     security/ca.key — your CA private key
     security/ca.crt — your CA certificate
     g-tls/server.key — your server private key
     g-tls/server.crt — your server certificate

   If your shell reports permission denied, mark the script as executable and rerun it:

   chmod +x make-certs.sh
   ./make-certs.sh

   The script creates two directories:

   • security/: Contains the CA certificate (ca.crt) and private key (ca.key)
   • g-tls/: Contains the server certificate (server.crt) and private key (server.key)

Certificate validity and production use

The certificates generated by this script are self-signed, intended only for local development, and expire after the short validity period defined in make-certs.sh.

For production deployments:

• Obtain certificates from a trusted Certificate Authority (CA) such as Let’s Encrypt, DigiCert, or your organization’s internal PKI.
• Issue certificates with the correct subject-alternative names for every AGS endpoint and automate rotation well before expiration.
• Enforce full certificate-chain and hostname validation on clients.
• Store private keys and CA material in a secrets manager or encrypted storage with tightly controlled access.
• Maintain a revocation process (CRL or OCSP) so compromised certificates can be invalidated quickly.

Understanding the Docker configuration

The docker-compose.yaml file mounts the certificates into the AGS container and enables TLS through environment variables.

Key configuration elements:

volumes:
  # Mount server cert and key for AGS to present to clients
  - ./g-tls:/opt/aerospike-graph/gremlin-server-tls:ro
  # Mount CA cert so AGS can load the certificate chain
  - ./security/ca.crt:/opt/aerospike-graph/gremlin-server-ca/ca.crt:ro

environment:
  # Enable TLS for the Gremlin WebSocket endpoint
  aerospike.graph-service.ssl.enabled: "true"

Here’s what each directive does:

• ./g-tls:/opt/aerospike-graph/gremlin-server-tls:ro supplies the server certificate and key that AGS presents to Gremlin clients. The directory must contain exactly one .crt and one .key file, mirroring the requirement in the product docs.
• ./security/ca.crt:/opt/aerospike-graph/gremlin-server-ca/ca.crt:ro lets AGS load the CA chain associated with that certificate so it can send the proper Intermediate/Root certs and satisfy clients that expect them.
• aerospike.graph-service.ssl.enabled: "true" flips on AGS’s TLS listener for the WebSocket endpoint at port 8182; without this flag AGS ignores the mounted certificates and continues serving plaintext traffic.

Leaving the volumes entries read-only (:ro) protects the certificates from being modified by the container.

Start the services

1. Start the Docker containers.

   docker-compose up -d

   Example response

   [+] Running 3/3
   ✔ Network gremlin-tls-asgraph-net  Created
   ✔ Container gremlin-tls-aerospike-db  Healthy
   ✔ Container gremlin-tls-aerospike-graph-service  Started

2. Wait for the services to become healthy (approximately 10 seconds).

   docker ps

   Both containers should show a status of “healthy” or “(healthy)” in the STATUS column.

Verify the connection

The tls_example.py script creates an SSL context, connects to AGS over WSS (WebSocket Secure), and runs a simple traversal.

1. Run the Python example.

   python3 ./tls_example.py

   Example response

   Attempt 1/5: Connecting to Graph...
   Connection established and healthy.
   Testing Connection to Graph
   Successfully Connected to Graph
   Values:
   ['aerospike', 'unlimited']
   Connected and Queried Successfully, TLS Between AGS and Gremlin is set!

2. Verify that the script output includes “TLS Between AGS and Gremlin is set!”.

How the client establishes TLS

The Python script uses the ssl module to create a context that trusts the CA certificate:

import ssl
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection

ssl_context = ssl.create_default_context(cafile="./security/ca.crt")
ssl_context.check_hostname = False

connection = DriverRemoteConnection(
    'wss://localhost:8182/gremlin',  # Note: wss:// for secure WebSocket
    'g',
    ssl_context=ssl_context
)

Here’s what those settings achieve:

• ssl.create_default_context(cafile="./security/ca.crt") loads the CA certificate that you created earlier. During the TLS handshake, Python checks that AGS presents a certificate signed by that CA before any Gremlin data moves across the network.
• The 'wss://localhost:8182/gremlin' endpoint forces the Gremlin driver to open a WebSocket-over-TLS tunnel so traversal requests and responses stay encrypted in transit.
• ssl_context.check_hostname = False relaxes hostname verification for this example because the certificate’s common name is exampleCluster instead of localhost. In production you should mint certificates whose Subject Alternative Names match the AGS hostnames and leave hostname checking enabled.
• Passing the custom ssl_context into DriverRemoteConnection propagates those trust rules down to the underlying WebSocket client, so every reconnection attempt continues to enforce the same CA and hostname policies.

Troubleshooting

If the Python script fails to connect:

Connection refused errors:

• Verify containers are running: docker ps
• Check AGS logs: docker logs gremlin-tls-aerospike-graph-service
• Ensure port 8182 is not already in use on your host

SSL certificate verification errors:

• Confirm the security/ca.crt file exists and is readable
• Check that certificate paths in docker-compose.yaml are correct
• Verify the CA certificate matches the server certificate (both signed by the same CA)

“Connection attempt N failed” with retries:

• AGS may still be initializing. Wait 10-15 seconds after docker-compose up -d
• Check that the database container is healthy: docker ps should show “healthy” status

Clean up

When you’re finished, stop and remove the containers:

docker-compose down

This command stops the containers and removes the network. The generated certificates remain in the security/ and g-tls/ directories for future use.

You’ve successfully configured TLS between a Gremlin client and AGS. The next step demonstrates TLS between AGS and Aerospike Database.

Checklist

• I’ve generated TLS certificates for the Gremlin-to-AGS connection.
• I’ve started AGS with TLS enabled.
• I’ve verified the secure connection using Python.