Skip to main content

Truststore Override for Delegates

Harness Delegates perform most Harness tasks. Delegates make outbound TLS/SSL connections to the Harness SaaS platform to obtain these task assignments. The TLS/SSL connection from the Delegate to Harness requires a trusted certificate.

Harness Delegates ship with a Java Runtime Environment (JRE) that includes a default trusted certificate in its truststore (located at jdk8u242-b08-jre/lib/security/cacerts). This truststore uses multiple trusted certificates, but you might want to limit these to conform to your company's security protocols.

Harness' only requirement is that the JRE truststore includes the certificate Delegates use to trust Harness (app.harness.io).

This topic describes how to limit the truststore used with Harness Delegates and ensure the trusted certificate Harness requires is included in the Delegate truststore.

In this topic:

Before You Begin

Required: Harness Trusted Certificate

TLS/SSL communication between the Harness Delegate and Harness SaaS uses a certificate from the DigiCert Global Root CA:

For Delegates to communicate with Harness, this root CA certificate needs to be installed in the Delegate's truststore.

The public key for the certificate is publicly available and can be downloaded. Here it is:

-----BEGIN CERTIFICATE-----  
MIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBD
QTAeFw0wNjExMTAwMDAwMDBaFw0zMTExMTAwMDAwMDBaMGExCzAJBgNVBAYTAlVT
MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IENBMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4jvhEXLeqKTTo1eqUKKPC3eQyaKl7hLOllsB
CSDMAZOnTjC3U/dDxGkAV53ijSLdhwZAAIEJzs4bg7/fzTtxRuLWZscFs3YnFo97
nh6Vfe63SKMI2tavegw5BmV/Sl0fvBf4q77uKNd0f3p4mVmFaG5cIzJLv07A6Fpt
43C/dxC//AH2hdmoRBBYMql1GNXRor5H4idq9Joz+EkIYIvUX7Q6hL+hqkpMfT7P
T19sdl6gSzeRntwi5m3OFBqOasv+zbMUZBfHWymeMr/y7vrTC0LUq7dBMtoM1O/4
gdW7jVg/tRvoSSiicNoxBN33shbyTApOB6jtSj1etX+jkMOvJwIDAQABo2MwYTAO
BgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUA95QNVbR
TLtm8KPiGxvDl7I90VUwHwYDVR0jBBgwFoAUA95QNVbRTLtm8KPiGxvDl7I90VUw
DQYJKoZIhvcNAQEFBQADggEBAMucN6pIExIK+t1EnE9SsPTfrgT1eXkIoyQY/Esr
hMAtudXH/vTBH1jLuG2cenTnmCmrEbXjcKChzUyImZOMkXDiqw8cvpOp/2PV5Adg
06O/nVsJ8dWO41P0jmP6P6fbtGbfYmbW0W5BjfIttep3Sp+dWOIrWcBAI+0tKIJF
PnlUkiaY4IBIqDfv8NZ5YBberOgOzW6sRBc4L0na4UU+Krk2U886UAb3LujEV0ls
YSEY1QSteDwsOoBrp+uvFRTp2InBuThs4pFsiv9kuXclVzDAGySj4dzp30d8tbQk
CAUw7C29C79Fv1C5qfPrmAESrciIxpg0X40KPMbp1ZWVbd4=
-----END CERTIFICATE-----

This topic describes how to import this certificate into a new truststore.

3rd Party Certificates

The Harness Delegate also connects to all of the 3rd party tools you are using with Harness. You will need to include those certificates in the Delegate truststore also.

For example, if you are pulling a Docker image from an artifact server like Nexus or DockerHub, the truststore will need the certificates required by those tools.

Step 1: Stop the Delegate

You set up the truststore before running a Delegate. You can stop a running Delegate, set it up to use the new truststore, and then restart it.

Shell Script Delegate

To stop a Shell Script Delegate, run:

./stop.sh

Docker Delegate

To stop a Docker Delegate, run:

docker stop harness/delegate

Kubernetes Delegate

You don't need to stop the Kubernetes Delegate. You can simply run kubectl apply again once you have updated the Kubernetes Delegate YAML file.

Step 2: Create Truststore with Harness Trusted Certificate

Let's walk through the steps of creating a new truststore and importing the Harness Trusted Certificate.

Copy the following public key to a file and save it.

-----BEGIN CERTIFICATE-----  
MIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBD
QTAeFw0wNjExMTAwMDAwMDBaFw0zMTExMTAwMDAwMDBaMGExCzAJBgNVBAYTAlVT
MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IENBMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4jvhEXLeqKTTo1eqUKKPC3eQyaKl7hLOllsB
CSDMAZOnTjC3U/dDxGkAV53ijSLdhwZAAIEJzs4bg7/fzTtxRuLWZscFs3YnFo97
nh6Vfe63SKMI2tavegw5BmV/Sl0fvBf4q77uKNd0f3p4mVmFaG5cIzJLv07A6Fpt
43C/dxC//AH2hdmoRBBYMql1GNXRor5H4idq9Joz+EkIYIvUX7Q6hL+hqkpMfT7P
T19sdl6gSzeRntwi5m3OFBqOasv+zbMUZBfHWymeMr/y7vrTC0LUq7dBMtoM1O/4
gdW7jVg/tRvoSSiicNoxBN33shbyTApOB6jtSj1etX+jkMOvJwIDAQABo2MwYTAO
BgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUA95QNVbR
TLtm8KPiGxvDl7I90VUwHwYDVR0jBBgwFoAUA95QNVbRTLtm8KPiGxvDl7I90VUw
DQYJKoZIhvcNAQEFBQADggEBAMucN6pIExIK+t1EnE9SsPTfrgT1eXkIoyQY/Esr
hMAtudXH/vTBH1jLuG2cenTnmCmrEbXjcKChzUyImZOMkXDiqw8cvpOp/2PV5Adg
06O/nVsJ8dWO41P0jmP6P6fbtGbfYmbW0W5BjfIttep3Sp+dWOIrWcBAI+0tKIJF
PnlUkiaY4IBIqDfv8NZ5YBberOgOzW6sRBc4L0na4UU+Krk2U886UAb3LujEV0ls
YSEY1QSteDwsOoBrp+uvFRTp2InBuThs4pFsiv9kuXclVzDAGySj4dzp30d8tbQk
CAUw7C29C79Fv1C5qfPrmAESrciIxpg0X40KPMbp1ZWVbd4=
-----END CERTIFICATE-----

In this example, we'll name the file DigiCertGlobalRootCA.pem.

Run the following command to create a truststore:

keytool -import -file DigiCertGlobalRootCA.pem -alias DigiCertRootCA -keystore trustStore.jks

The above command will ask for a password. You can choose your own password.

This command creates a file named trustStore.jks and imports DigiCert global root CA certificate.

Note where the trustStore.jks is located. You will provide this path to the Delegate as an environment variable.

Step 3: Add 3rd Party Certificates to the Truststore

You should import any certificates required by the 3rd party tools you use with Harness.

In most cases, you can navigate to the 3rd party tool's website portal and download the certificate using a Copy or Export button in the browser. Simply save the certificate as a PEM (.pem) file and then import it into the truststore.

To add multiple certificates in the trustStore.jks you created, simply run the keytool -import command multiple times with the different aliases and certificate PEM files for the certificates you are importing.

Step 4: Update the Delegate JAVA_OPTS Environment Variable

Now that you have a new truststore, you need to update the Delegate JAVA_OPTS environment variable to point to the location of the new truststore file.

Shell Script Delegate

SSH into the host and navigate to where the start.sh for the Delegate is located.

Next, provide the path of the new truststore using JAVA_OPTS and the password.

export JAVA_OPTS="-Djavax.net.ssl.trustStore=<path/to/trustStore.jks> -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=<password>"

Next, you can run the Delegate install script, described in the next step.

Docker Delegate

​For the Docker Delegate, you need to edit the Delegate shell file. The file is named launch-harness-delegate.sh.

Open launch-harness-delegate.sh in an editor.

In the sudo docker run section of the file, add a new environment variable (-e) that provides the path of the new truststore using JAVA_OPTS and the password:

sudo docker run -d --restart unless-stopped --hostname=$(hostname -f) \  
...
-e JAVA_OPTS="-Djavax.net.ssl.trustStore=<path/to/trustStore.jks> -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=<password>"
...

Next, you can run the Delegate install script, described in the next step.

Kubernetes Delegate

For the Kubernetes Delegate, you need to edit the Delegate YAML file. It's named harness-delegate.yaml.

Open the Delegate YAML file in a text editor.

In the StatefulSet manifest, under env, locate JAVA_OPTS.

Here's what the default setting looks like:

...  
apiVersion: apps/v1
kind: StatefulSet
...
spec:
...
spec:
...
env:
- name: JAVA_OPTS
value: "-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -XX:MaxRAMFraction=2 -Xms64M"
...

Update the JAVA_OPTS environment variable with the location of the new trustStore.jks file and the password.

For example:

      ...  
env:
- name: JAVA_OPTS
value: "-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -XX:MaxRAMFraction=2 -Xms64M -Djavax.net.ssl.trustStore=<path/to/trustStore.jks> -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=<password>"
...

Next, you can apply the Delegate YAML file, described in the next step.

Step 5: Start the Delegate

Now that the JAVA_OPTS environment variable is updated, you can start the Delegate.

Shell Script Delegate

To start the Delegate, you will need to run the following command where the start.sh for the Delegate is located:

./start

The Delegate will start and in a few moments you will see it listed in the Harness Delegates page.

Docker Delegate

Run the start script ($ ./launch-harness-delegate.sh). You will see the Docker image pull, for example:

latest: Pulling from harness/delegate  
297061f60c36: Pull complete…
Status: Downloaded newer image for harness/delegate:latest

The Delegate will start and in a few moments you will see it listed in the Harness Delegates page.

Kubernetes Delegate

Apply the Kubernetes Delegate YAML file you edited:

kubectl apply -f harness-delegate.yaml

The Delegate will start and in a few moments you will see it listed in the Harness Delegates page.

See Also