Skip to main content

Install delegates with custom certificates

This topic explains how to install Kubernetes, Docker, and Helm delegates with custom certificates.

caution

The installation steps are different depending on your delegate version.

If your delegate with an immutable image type version is later than 81202 (image tag 23.10.81202), go to Install with custom certificates.

If your delegate with an immutable image type version is earlier than 81202 (image tag 23.10.81202), go to Install with custom truststore.

For information on delegate types, go to Delegate image types.

Install with custom certificates​

Use the steps below to install custom certificates for a Docker, Kubernetes, or Helm delegate with an an immutable image type version later than 23.10.81202.

note

You might need additional permissions to execute commands in delegate scripts and create Harness users.

To install a Docker delegate with custom certificates, do the following:

  1. Prepare the custom cert file(s).

    note

    Certificates must be PEM format.

  2. Mount the file(s) to the /opt/harness-delegate/ca-bundle/ directory inside the delegate container.

  3. Start the delegate with the root user.

    Example: Mount custom certs from a folder

    docker run --cpus=1 -u root --memory=2g \
      -v PUT_YOUR_PATH_TO_FOLDER_OF_CUSTOM_CERTS:/opt/harness-delegate/ca-bundle \
      -e DELEGATE_NAME=PUT_YOUR_DELEGATE_NAME \
      -e NEXT_GEN="true" \
      -e DELEGATE_TYPE="DOCKER" \
      -e ACCOUNT_ID=PUT_YOUR_HARNESS_ACCOUNTID_HERE \
      -e DELEGATE_TOKEN=PUT_YOUR_HARNESS_ACCOUNTID_HERE \
      -e LOG_STREAMING_SERVICE_URL=PUT_YOUR_MANAGER_HOST_AND_PORT_HERE/log-service/ \
      -e MANAGER_HOST_AND_PORT=PUT_YOUR_MANAGER_HOST_AND_PORT_HERE  harness/delegate:yy.mm.verno

    Example: Mount a single custom cert or a CA bundle file

    docker run --cpus=1 -u root --memory=2g \
      -v PUT_YOUR_PATH_TO_CUSTOM_CERT:/opt/harness-delegate/ca-bundle/abc.pem \
      -e DELEGATE_NAME=PUT_YOUR_DELEGATE_NAME \         
      -e NEXT_GEN="true" \
      -e DELEGATE_TYPE="DOCKER" \
      -e ACCOUNT_ID=PUT_YOUR_HARNESS_ACCOUNTID_HERE \
      -e DELEGATE_TOKEN=PUT_YOUR_HARNESS_ACCOUNTID_HERE \
      -e LOG_STREAMING_SERVICE_URL=PUT_YOUR_MANAGER_HOST_AND_PORT_HERE/log-service/ \
      -e MANAGER_HOST_AND_PORT=PUT_YOUR_MANAGER_HOST_AND_PORT_HERE  harness/delegate:yy.mm.verno

Install with custom truststore​

Harness Delegate ships with a Java Runtime Environment (JRE) that includes a default trusted certificate in its truststore located in the /opt/java/openjdk/lib/security/cacerts directory. This truststore uses multiple trusted certificates. You can limit the number you use based on your company's security protocols.

The JRE truststore must include the certificate that delegates require to establish trust with Harness (app.harness.io).

Command-line tools use truststore from the underlying Red Hat operating system.

Use the steps below to install custom certificates for a Docker or Kubernetes delegate with an an immutable image type version earlier than 23.10.81202.

There are two aspects of custom certificates:

  1. A certificate for the delegate Java process, which makes connections to external systems.

  2. A certificate for the OS itself. With this certificate, if another process, such as a shell script, is spawned, it can access custom certificates.

In this topic, we will do the following:

  • Create a custom truststore.
  • Create a secret.
  • Add a volume mount to the harness-delegate.yaml file and provide it to the delegate Java process.
  • Add a volume mount to the harness-delegate.yaml file and configure the delegate container OS to have the certificates.
note

Harness recommends that you keep your existing Java KeyStore in place during the installation process. Updating the KeyStore may cause issues with your delegate.

For information on best practices for truststore creation, go to Java Keystore Best Practices.

Create a custom truststore​

  1. Prepare the custom cert file(s).

    note

    Certificates must be PEM format.

  2. (Optional) Get a base truststore file from a running delegate instance.

    Kubernetes delegate

    kubectl cp -n harness-delegate-ng [pod name]:/opt/java/openjdk/lib/security/cacerts Path/to/destination

    Docker delegate

    docker cp [container id]:/opt/java/openjdk/lib/security/cacerts Path/to/destination

  3. Import custom certs into the Java truststore.

    a. Split the certificates into individual files if the custom cert file contains multiple certificates.

    b. Run the keytool command below for each certificate file to import them.

    keytool -noprompt -import -trustcacerts -file [cer file] -alias [unique alias] -keystore [path to trust store] -storepass [password]

    c. Replace the password placeholder with the password you gave your truststore.

    d. Use a unique alias for all imports.

Install truststore and custom certs​

After the truststore file and custom certificates are configured, you're ready to install them in a Kubernetes or Docker delegate.

  1. Mount the truststore file to the delegate container.

  2. Mount the custom certificates to the /etc/pki/ca-trust/source/anchors/ directory.

  3. Run the delegate container with the root user.

  4. Add update-ca-trust to INIT_SCRIPT.

    Example command

    docker run --cpus=1 --memory=2g -u root \
      -v PUT_YOUR_PATH_TO_CUSTOM_CERT:/etc/pki/ca-trust/source/anchors/ca1.pem \
      -v ... repeat for every custom cert ... \
      -v PUT_YOUR_PATH_TO_TRUSTSTORE:/cacerts/harness_trustStore.jks \
      -e JAVA_OPTS="... -Djavax.net.ssl.trustStore=/cacerts/harness_trustStore.jks -Djavax.net.ssl.trustStorePassword=password" \
      -e INIT_SCRIPT="update-ca-trust" \
      -e DELEGATE_NAME=PUT_YOUR_DELEGATE_NAME \
      -e NEXT_GEN="true" \
      -e DELEGATE_TYPE="DOCKER" \
      -e ACCOUNT_ID=PUT_YOUR_HARNESS_ACCOUNTID_HERE \
      -e DELEGATE_TOKEN=PUT_YOUR_HARNESS_ACCOUNTID_HERE \
      -e LOG_STREAMING_SERVICE_URL=PUT_YOUR_MANAGER_HOST_AND_PORT_HERE/log-service/ \
      -e MANAGER_HOST_AND_PORT=PUT_YOUR_MANAGER_HOST_AND_PORT_HERE  harness/delegate:yy.mm.verno