API References
Grainite Homepage

Enabling TLS

The scripts used in this guide are the same as those downloaded at the beginning of the cluster deployment pages for AWS and GCP.

If you are using a gx version older than 2323.1, please follow the instructions on the Enabling TLS (pre-2323.1) page instead.

Step 1: Securing a 3-node cluster

Note: The user running these steps should be the same user that created the Grainite cluster.

Note: This step can be skipped if you directly created a secure cluster.

Run the following command to enable encryption for your cluster, from where the cluster VPC is accessible:

./grainite/scripts/bin/gcp-grainite cluster-secure -h


cluster-secure: Secures the current unsecure grainite cluster with TLS certs, disk encryption if enabled


Usage:
    cluster-secure CLUSTER_NAME [flags]


Envs:
    GXS_CERTS_KEYS_DIR:
        Default GXS_CERTS_KEYS_DIR=${HOME}/.gxscerts/


        For secure setup of grainite cluster and enabling disk encryption you need to export this env.
        The server CA CERTS, client certs and encryption KEYS will be generated under


            ${GXS_CERTS_KEYS_DIR}/<cluster-name>/{server/, client/, keys/}


Flags:
    -e:         enable disk encryption also, default only TLS setup
    -R:         region

  • <region> is the cluster's region

cluster-secure generates a unique CA (self-signed certificate and private key) for the provided cluster into the provided directory. In the next step, the CA private key will be used to issue certificates to allow clients to connect to this cluster.

Step 2: Generate client certificates and private keys

The following command can be run to generate client certificates.

./grainite/scripts/bin/gcp-grainite gen-client-cert -h

gen-client-cert: Generates client cert to connect to secured grainite
cluster returned by 'cluster-current'

Usage:
    gen-client-cert CERT-USER-NAME 

Envs:
    GXS_CERTS_KEYS_DIR:
        Default GXS_CERTS_KEYS_DIR=${HOME}/.gxscerts/
 
        For secure setup of grainite cluster and enabling disk encryption
        you need to export this env.  The CA CERTS, client certs and
        encryption KEYS will be generated under

            ${GXS_CERTS_KEYS_DIR}/<cluster-name>/{server/, client/, keys/}

        The client certs will be generated for the user and signed by
        the CA certs. Zip file will be available under

            ${GXS_CERTS_KEYS_DIR}/<cluster-name>/client/

        Additionally PCKS12 cert will also be generated with the provided
        password for using with GX command

Where:

  • CERT-USER-NAME is the name of the user for whom to generate the certificate.

  • PKCS12-CERT-PASSWORD is the password to use for the certificate.

    • NOTE: This argument will be removed in a future release.

Example

./grainite/scripts/bin/gcp-grainite gen-client-cert tom password

The client certs, key, and a file with the server ip will be created under ${GXS_CERTS_KEYS_DIR}/<cluster-name>/client/<CERT-USER-NAME>. Distribute these files to the user.

Step 3: Configure TLS support for gx

Next, the user must run the following commands to set the paths for the certificates in their $HOME.gx:

  1. Set the ca cert:

gx config ca_cert_path /path/to/ca/grainite_ca.crt

  1. Set the client cert:

gx config client_cert_path /path/to/cert/grainite_client.<CERT-USER-NAME>.crt

  1. Set the client key:

gx config client_key_path /path/to/key/grainite_client.<CERT-USER-NAME>.key

To prevent having to specify the IP address of your cluster each time you use gx commands, you can run the following to set the ip: gx config host $(cat /path/to/server_ip)

Step 4: Use the secure Java client API

Once all the certificates and keys have been generated, the next step is to pass them to the java API in order to access the cluster securely Ensure that settings.xml exists under .m2 directory with the credentials for the private token before running maven.

You can get the server ip by running the command on AWS: kubectl get svc gslb -ojsonpath={'.status.loadBalancer.ingress[0].hostname'}

For GCP, the command is kubectl get svc gslb

Grainite grainite = GrainiteClient.getClient(<server ip>, 5056, <ca cert>, <client cert>, <client key>, <env>);

Where:

  • <server ip> is the IP address of the cluster.

  • <ca cert> is the path to the CA certificate generated in step 1.

  • <client cert> is the path the client certificate generated in step 2.

  • <client key> is the path to the client key generated in step 2.

  • <env> is the name of the environment for the application.

PreviousSecuring your ClusterNextEnabling TLS (pre-2323.1)

Last updated