Skip to content

Custom Root of Trust

Welkin has support for custom root of trust as a separate feature. If you are unsure if the feature is enabled in your environment or have any other questions around it, please contact your platform administrator.

The custom root of trust feature in Welkin provides the means to configure the cryptographic root of trust in your (encryption) key infrastructure. Typical uses include setting up and managing a certificate authority (CA) service that issues all certificates within an enterprise, to ensure that no outside dependencies exist and that all certificates are controlled by an internal department. The custom root of trust feature makes Welkin, and services deployed onto it, trust only certificates that have been issued by a set of CAs your organization deems trustworthy, whether that is only your internal one, or a default list of public CAs in addition to your internal one. This page explains how Application Developers can easily get the CA certificates, or any number of other custom certificates, injected into their application deployments.

Injection for Pods is controlled by what mode is configured, either OptOut or OptIn. In OptIn mode, Pods are injected by adding the annotation elastisys.io/inject-custom-ca and setting the value to the name of the bundle you want a Pod to inject. If using OptOut mode, all Pods are injected with the configured default bundle. Pods can be opt-out by setting the annotation with an empty string as value: elastisys.io/inject-custom-ca="" For a Pod to pick up and use the bundle, the injection adds the SSL_CERT_FILE environment variable to point to the mount path of the bundle, and also adds SSL_CERT_DIR=/dev/null to better guarantee that the application running actually picks it up.

Note

To help protect against misconfigured annotations, a ValidatingPolicy is in place that rejects deploying Pods attempting to mount non-existing ConfigMaps:

$ kubectl apply -f my-app.yaml
Error from server: error when creating "manifests/my-app.yaml": admission webhook "vpol.validate.kyverno.svc-fail-finegrained-elastisys-check-bundle-cm-exists" denied the request: Policy elastisys-check-bundle-cm-exists failed: Bundle ConfigMap "non-existing-bundle" not found in default. Please verify that the name is correct. If the name is correct but you still get this error, please contact your platform administrator.

Adapting the injection for your application

Welkin will set SSL_CERT_FILE to the location of the bundle and SSL_CERT_DIR=/dev/null which makes most applications pick up the custom root of trust. However, setting SSL_CERT_FILE is not guaranteed to work for all applications. For example, Java applications are known to not use this, instead, you need the bundle to be part of the Java Truststore which can have different locations for each Java application.

The sections below clarify extra steps needed to be taken for Java applications, Node.js applications, and applications incorporating the AWS SDK.

Note

If your application is not covered in the examples below and is still experiencing certificate errors, please consult your framework's official documentation to determine how it manages custom trust stores and SSL/TLS certificates.

Java application example

apiVersion: v1
kind: Pod
metadata:
  annotations:
    elastisys.io/inject-custom-ca: "" # make sure to opt-out from mutating policy
  name: opensearch-master
spec:
  containers:
    ...
    volumeMounts:
    ...
    - mountPath: /usr/share/opensearch/jdk/lib/security/cacerts # specific java truststore location for opensearch
      name: elastisys-etc-ssl-certs
      subPath: cacerts
  ...
  volumes:
  - configMap:
      defaultMode: 420
      items:
      - key: cacerts.jks # the default bundle configmap will have a bundle in java truststore format (jks)
        path: cacerts
      name: default-bundle
    name: elastisys-etc-ssl-certs

Some applications require specific environment variables to be set for them to use a custom bundle. There are some additional annotations supported in Welkin to inject such environment variables:

  • elastisys.io/inject-custom-ca-type: nodejs will inject the NODE_EXTRA_CA_CERTS environment variable to have the value: /etc/ssl/certs/ca-certificates.crt.
  • elastisys.io/inject-custom-ca-type: aws will inject the AWS_CA_BUNDLE environment variable to have the value: /etc/ssl/certs/ca-certificates.crt.

Node.js application example

apiVersion: v1
kind: Pod
metadata:
  annotations:
    # elastisys.io/inject-custom-ca: "bundle-name" # If using OptIn, set this to value of name of bundle that should be injected
    elastisys.io/inject-custom-ca-type: nodejs
  name: node-app
spec:
  ...

Application using AWS SDK example

apiVersion: v1
kind: Pod
metadata:
  annotations:
    # elastisys.io/inject-custom-ca: "bundle-name" # If using OptIn, set this to value of name of bundle that should be injected
    elastisys.io/inject-custom-ca-type: aws
  name: app-using-aws-sdk
spec:
  ...

References