API References
Grainite Homepage

Enabling TLS (pre-2323.1)

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

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: Configure client certificates and private keys

The following command can be run to generate client certificates.

Also generates certificate for HTTPS requests made in gx command. GX makes HTTPS calls to the server in order to get the status of the server as well as counters from the server via gx mon.

./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 PKCS12-CERT-PASSWORD


    PKCS12-CERT-PASSWORD
            PKCS12 cert password, will be prompted for password if not
            specified, min 8 chars

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. This will later be required to use the certificate by gx using --pass.

Example

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

To validate the certificate, the CA certificate will also need to be added to the trust store using the following command:

sudo keytool -import -alias <alias> -keystore $JAVA_HOME/lib/security/cacerts -file <ca certificate>> -storepass <store_password> -noprompt

On Linux, run the following to set JAVA_HOME:

JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:bin/java::")

Where:

  • <alias> is a unique identifier.

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

  • <store_password> can be the same password as PKCS12-CERT-PASSWORD

Step 3: Configure TLS support for gx

Copy the client certificates into the samples/certs directory:

cp ~/.gxcerts/client/<CLUSTER_NAME>/client/* ~/samples/certs

You must also create a password file inside the samples/certs directory:

cd ~/samples/certs
vi password

Inside password, the contents must be in this format:

password: <changeit>

Replace <changeit> with the password you used to create the client certificates in the previous step (PKCS12-CERT-PASSWORD).

Then, in the samples/gx file, you must edit the paths to the certificates to match the paths of the certificates you created:

Originally looks like this:

samples/gx
...
CLIENT_CERT="${BASEDIR}/certs/grainite_client.test-client.crt"
CLIENT_KEY="${BASEDIR}/certs/grainite_client.test-client.key"
P12_CERT="${BASEDIR}/certs/grainite_client.test-client.p12"
CA_CERT="${BASEDIR}/certs/grainite_ca.crt"
...

You'll replace test-client with the CERT-USER-NAME you specified in step 2:

CLIENT_CERT="${BASEDIR}/certs/grainite_client.<CERT-USER-NAME>.crt"
CLIENT_KEY="${BASEDIR}/certs/grainite_client.<CERT-USER-NAME>.key"
P12_CERT="${BASEDIR}/certs/grainite_client.<CERT-USER-NAME>.p12"
CA_CERT="${BASEDIR}/certs/grainite_ca.crt"

To prevent having to specify the IP address of your cluster each time you use gx commands, you can perform the following steps:

  1. Create and open a file named server_ip: vi server_ip

  2. Paste in your cluster IP address and save and close the file. (You can get the cluster IP with one of the below commands, based on your cloud provider): gcp-grainite cluster-ip aws-grainite cluster-ip azure-grainite cluster-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.

PreviousEnabling TLSNextEnabling Disk Encryption

Last updated