Documentation Suite v25.2

Submit Search

Install the Universal Orchestrator in a Linux Container

When the Keyfactor Universal Orchestrator The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers. runs in a Linux container, it is typically installed in a containerization solution that sits on top of a Linux server or set of servers. There are a wide variety of containerization solutions for multiple operating systems. This document covers deploying the container to either Docker or Kubernetes on Linux.

The artifactory for the Universal Orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. images for Docker and Kubernetes without Helm can be found in the following JFrog repository:

repo.keyfactor.com/images/command/

The artifactory for the Universal Orchestrator Helm charts can be found in the following JFrog repository:

repo.keyfactor.com/charts/command/

Two different images are available, depending on the functionality you are looking for:

universal-orchestrator:[version]

This image has no built-in functionality and is designed to be used with custom extensions.
universal-orchestrator-ssl:[version]

This image provides the SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. capability to provide support for SSL discovery and monitoring.

Note: For artifactory credentials or more information, check with your Keyfactor Client Success Manager or contact support@keyfactor.com.

Docker

If you plan to use Docker, you may find it helpful to first run the Universal Orchestrator in the foreground so that it will output log messages to assist in troubleshooting.

Tip: If your Docker implementation hasn’t been configured to inject your DNS

The Domain Name System is a service that translates names into IP addresses. server(s) into running containers, you may wish to do this so that the Universal Orchestrator will be able to do name resolution. To do this, on the Linux server(s) where you are running Docker, create or update the /etc/docker/daemon.json file, and add an entry similar to the following:

{"dns": ["DNS_IP_Address_1", "DNS_IP_Address_2"] }

To install the Universal Orchestrator in a Linux container and start the container using compose:

Create a directory from which you will run the Docker container (e.g. /opt/kyf_uo). For example:

sudo mkdir /opt/kyf_uo
Select a Universal Orchestrator image, and from your Docker host, retrieve the Universal Orchestrator image from the artifactory with commands similar to the following (placing your token or API An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. key in the my_password file):

sudo nano my_password.txt

cat my_password.txt | docker login repo.keyfactor.com --username username --password-stdin

docker pull repo.keyfactor.com/images/command/universal-orchestrator-ssl:25.2

Note: For artifactory credentials or more information, check with your Keyfactor Client Success Manager or contact support@keyfactor.com.

Important: Remove the my_password.txt file when complete. For example:
sudo rm my_password.txt

Create a Docker compose file (compose.yaml) in the directory for your Docker container similar to the following, using the inputs as per Table 1034: Linux Container Parameters for Docker, referencing the artifictory you pulled, selecting the appropriate authentication mechanism for your environment, and any additional volume mounts (see Custom Extensions with Docker). The fields highlighted in red below indicate fields that need to be edited or that you may wish to edit

Important: When editing the file, be sure to preserve the indenting exactly as shown. YAML requires a very specific file layout to function. If the indenting (multiples of two spaces) or layout is incorrect, you will receive an error when trying to install.

services:
  universal-orchestrator:
    image: repo.keyfactor.com/images/command/universal-orchestrator-ssl:25.2
    container_name: universal_orchestrator-1
    environment:
      COMMAND_AGENTS_URL: https://keyfactor.keyexample.com/KeyfactorAgents
      ORCHESTRATOR_NAME: appsrvr19-UO-1 # The name the orchestrator uses to register in Keyfactor Command
      # Uncomment the next two lines to use Active Directory
      #USERNAME: KEYEXAMPLE\svc_kyforch
      #PASSWORD: 'MySuperSecretPassword' # The service account password needs quotes under some circumstances if it contains special characters
      # Uncomment the next four lines to use OAuth (TOKEN_LIFETIME is optional)
      #BEARER_TOKEN_URL: https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token
      #TOKEN_LIFETIME: 150
      #CLIENTID: Universal-Orchestrator
      #CLIENT_SECRET: 'Client-Secret-from-Keyfactor-IdP' # The client secret needs quotes under some circumstances if it contains special characters
    volumes:
      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-bundle.crt # The path on your host (the first one) will vary depending on the OS

Important: The password or secret for the Keyfactor Command connect service account is stored in clear text in this compose file. Access to this file should be strictly controlled.

Set the permissions on the compose.yaml file such that the file is owned by root and readable only by root (this assumes your Docker daemon is running as root, which is typical). For example:

sudo chown root:root compose.yaml

sudo chmod 400 compose.yaml

Tip: If you need to make edits to the compose file, you will need to make the file writable again. For example:
sudo chmod 600 compose.yaml
Execute the following command to install and run the container in the foreground:

sudo docker compose up

Press CTRL-C to stop it if it’s running in the foreground. You can instead run it in the background by adding the -d flag like so, but it can sometimes be helpful to run it in the foreground initially so that you can easily review the log output live:

sudo docker compose up -d
Tip: To stop and start the container again after installation is complete, use the following commands:
sudo docker compose stop
sudo docker compose start
Or:
sudo docker compose restart
If you need to delete the container and try the install again, use this command:
sudo docker compose down
To review logs generated from the container, identify the container ID or name with this command:
sudo docker container ls
Or for a more succinct output:
Copy
```
sudo echo "CONTAINER ID  NAMES       STATUS" && docker container ls --format "{{.ID}}  {{.Names}}  {{.Status}}"
```
For example, in the following output (this is the succinct version) you could select either the container ID e67063a956c3 or the name universal_orchestrator-1:
```
CONTAINER ID  NAMES       STATUSe67063a956c3universal_orchestrator-1  Up 4 weeks
daa0b06986c3  ejbca900  Up 4 weeks
9136a6765450  ejbca900-database  Up 4 weeks
7cf64de25b4d  ejbca920  Up 4 weeks
4451b1ef5089  ejbca920-database  Up 4 weeks
94a373b2f49a  rabbit-mq  Up 4 weeks
```
Then use the following command to output the current log (with the optional --follow to make output continuous):
sudo docker container logs [--follow] [container ID or name]

Custom Extensions with Docker

To use custom extensions with the orchestrators (see Installing Certificate Store Management Extensions), you can either build them into a custom-built orchestrator image or reference them as external volume mounts. The latter works well for quick testing in a development environment, but you’ll probably want to use a custom-built orchestrator image for a production deployment.

Tip: For information on installing remote PAM extensions, see Remote PAM Extensions on the Keyfactor Universal Orchestrator Server (Container).

To run the orchestrator referencing an extension as an external volume mount:

Create a directory on your Linux server to host the extension(s) you wish to use and copy each extension you wish to use into this directory. For example:

/opt/kyf_uo/exts/f5-ext

/opt/kyf_uo/exts/citrix-ext

Make note of whether the extension documentation indicates whether the files in the extension need to exist within a subdirectory or whether they should be placed in the root of the directory you’re creating (e.g. f5-ext).

Follow the instructions above, but modify the volumes section of your docker compose file to include the extension(s). For example (where /app/extensions is the path within the image where the extensions will live):

#[See beginning above]
    volumes:
      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-bundle.crt
      - /opt/kyf_uo/exts/f5-ext:/app/extensions/f5-ext
      - /opt/kyf_uo/exts/citrix-ext:/app/extensions/citrix-ext

To create a custom build of the orchestrator referencing extensions:

Create a directory on your Linux server to host the extension(s) you wish to use and copy each extension you wish to use into this directory. This should be a subdirectory of the directory in which you will build your custom orchestrator image. For example:

/opt/kyf_uo/exts/f5-ext

/opt/kyf_uo/exts/citrix-ext

Make note of whether the extension documentation indicates whether the files in the extension need to exist within a subdirectory or whether they should be placed in the root of the directory you’re creating (e.g. f5-ext).
In the directory above the extension directory (e.g. /opt/kyf_uo), create a file called Dockerfile and open it for editing. The entries in this file will vary depending on the extension(s) you wish to include in your build. Check the documentation for the specific extension for more information. The following example includes two extensions:
```
FROM repo.keyfactor.com/images/command/universal-orchestrator:25.2
WORKDIR "/app/extensions/f5-ext"
COPY ./ext/f5-ext/ ./
WORKDIR "/app/extensions/citrix-ext"
COPY ./ext/citrix-ext/ ./
WORKDIR "/app"
```
This build script sets the source for the artifactory and then changes directories within the image to the f5-ext directory. It copies the contents of the ext/f5-ext subdirectory under the current working directory on the host to the current directory in the image. It then repeats this change directory and copy for the Citrix Netscaler extension. Finally, it changes directory back to the /app directory within the image before leaving the build. This last step is important to be sure the image will later function as expected.
Build your custom image by executing the following command from the directory in which your Dockerfile is located (where custom-uo-image is the name you give to your image):

docker build -t custom-uo-image .

Create your compose file as above, but referencing your custom image like so:

  services:
    universal-orchestrator:
      image: custom-uo-image
      container_name: universal_orchestrator_f5_ns
#[see remainder above]

Complete the install as above.

Table 1034: Linux Container Parameters for Docker

Parameter	Description
AppSettings__CheckServerCertificateRevocation	A Boolean that indicates whether the revocation status (CRL) of the SSL certificate on the Keyfactor Command server should be checked when connecting to Keyfactor Command (true) or not (false). The default is true (CRL checking will be done).
AUDIENCE	This parameter is used to specify an audience value to be included in token requests delivered to the identity provider when using an identity provider other than Active Directory.
BEARER_TOKEN_URL	Required^*. The URL of the token endpoint for your identity provider. For example: Copy `https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token` For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation). This parameter is required if you’re using an identity provider other than Active Directory.
CLIENTID	Required^*. For implementations using an identity provider other than Active Directory, the ID of the identity provider client that should be used to authenticate the session (see Create Service Accounts for the Universal Orchestrator). This parameter is required if you’re using an identity provider other than Active Directory.
CLIENT_SECRET	Required^*. For implementations using an identity provider other than Active Directory, the secret of the identity provider client that should be used to authenticate the session. This parameter is required if you’re using an identity provider other than Active Directory.
COMMAND_AGENTS_URL	Required. The URL of the Orchestrators API on the Keyfactor Command server. For example: Copy `https://keyfactor.keyexample.com/KeyfactorAgents`
LOG_LEVEL	The logging level for the orchestrator. The default value is Info. Possible values are the same as those described in Configure Logging for the Universal Orchestrator.
ORCHESTRATOR_NAME	The name the orchestrator uses to register itself with Keyfactor Command. By default, the container hostname is used, which is not ideal as this will create a new orchestrator entry with every container start. Although this parameter is not strictly required, Keyfactor strongly recommends using it. If you choose to uninstall and reinstall the orchestrator (e.g. using compose down), it is important to use the same orchestrator name for subsequent implementations so that Keyfactor Command will recognize the orchestrator when it is started again.
PASSWORD	Required^*. The password for the Keyfactor Command Connect Service Account if you’re using Active Directory as an identity provider (see USERNAME). This parameter is required if you’re using Active Directory as an identity provider.
SCOPE	This parameter is used to specify one or more scopes that should be included in token requests delivered to the identity provider when using an identity provider other than Active Directory. Multiple scopes should be separated by spaces.
TOKEN_LIFETIME	For implementations using an identity provider other than Active Directory, the number of seconds for which the bearer token is valid. If not specified, the orchestrator uses the default value set by the Keyfactor Command server of 300 seconds (5 minutes).
USERNAME	Required^*. The username for service account used to connect to the Keyfactor Command server (see PASSWORD). This is the Keyfactor Command Connect Service Account described in Create Service Accounts for the Universal Orchestrator if you’re using Active Directory as an identity provider. The orchestrator uses Basic Authentication to authenticate to Keyfactor Command. This parameter is required if you’re using Active Directory as an identity provider.

Kubernetes without Helm

To deploy the container as a StatefulSet in Kubernetes without using Helm, manually define a Kubernetes manifest (YAML file) specifying the StatefulSet resource. This includes configuring the container image, environment variables, volume mounts, and other settings needed for deployment. The container will run within the StatefulSet, ensuring persistence and unique network identities for each pod.

To install the Universal Orchestrator using Kubernetes without Helm:

Create a directory from which you will run the container (e.g. /opt/kyf_uo).
If desired, create a namespace for Universal Orchestrator resources and containers in Kubernetes. For example:

sudo kubectl create namespace keyfactor-orchestrators
Create a secret in Kubernetes to allow the Universal Orchestrator to authenticate to Keyfactor Command (see Create Service Accounts for the Universal Orchestrator).

For example, for Active Directory authentication:

sudo kubectl create secret generic uo-credentials --namespace keyfactor-orchestrators --from-literal=username=KEYEXAMPLE\svc_kyforch --from-literal=password=MySuperSecretPassword

For OAuth authentication:

sudo kubectl create secret generic uo-credentials --namespace keyfactor-orchestrators --from-literal=clientid=Universal-Orchestrator --from-literal=clientsecret=MySuperSecretClientSecret
Create a secret in Kubernetes for the credentials you will use to authenticate to the Keyfactor artifactory. For example:

sudo kubectl create secret docker-registry keyregcred --namespace keyfactor-orchestrators --docker-server=repo.keyfactor.com --docker-username=MyUsername --docker-password=MySuperSecretToken --docker-email=my.email@my-domain.com

Note: For artifactory credentials or more information, check with your Keyfactor Client Success Manager or contact support@keyfactor.com.
Create a ConfigMap in Kubernetes containing CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. root and issuing certificates for all CAs in the environment that will have any relationship with the Universal Orchestrator (see Configure Certificate Root Trust for the Universal Orchestrator).

Once the host’s trust store is updated with all the certificates you will need, create the ConfigMap. For example:

sudo kubectl create configmap ca-roots --namespace keyfactor-orchestrators --from-file=/etc/ssl/certs/ca-certificates.crt

Note: The standard path to the trusted root store will vary depending on your Linux implementation.

Create a Kubernetes deployment file (e.g. uo_ssl.yaml) in the directory for your Kubernetes container similar to the following, using the inputs as per Table 1035: Linux Container Parameters for Kubernetes without Helm, referencing the artifactory for the image you wish to install, selecting the appropriate authentication mechanism for your environment, and any additional volume mounts. The fields highlighted in red below indicate fields that need to be edited or that you may wish to edit.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  # Give the pod a unique name if you plan to deploy more than one orchestrator to the same Kubernetes server or cluster
  name: keyfactor-uo-1
  labels:
    app.kubernetes.io/name: keyfactor-universal-orchestrator
    app.kubernetes.io/instance: ssl-1
    app.kubernetes.io/version: "25.2"
spec:
  # The universal orchestrator should not have replicas; instead use many different deployments with different names if horizontal scaling is needed
  serviceName: keyfactor-uo-service
  replicas: 1

  selector:
    matchLabels:
      app.kubernetes.io/name: keyfactor-universal-orchestrator
      app.kubernetes.io/instance: ssl-1

  template:
    metadata:
      labels:
        app.kubernetes.io/name: keyfactor-universal-orchestrator
        app.kubernetes.io/instance: ssl-1

    spec:
      initContainers:
        # See separate section for example of adding a custom extension

      containers:
        - name: keyfactor-universal-orchestrator-ssl-1
        # Uncomment the desired image and confirm correct artifactory and version
        image: "repo.keyfactor.com/images/command/universal-orchestrator-ssl:25.2"
        #image: "repo.keyfactor.com/images/command/universal-orchestrator:25.2"
        imagePullPolicy: IfNotPresent
        # Universal orchestrator environment

        env:
          # The below block is the URL of the orchestrator API on the Keyfactor Command server
          - name: COMMAND_AGENTS_URL
            value: https://keyfactor.keyexample.com/KeyfactorAgents
          # The below block is the name the orchestrator will use when registering with Keyfactor Command
          - name: ORCHESTRATOR_NAME
            value: k8s-universal-orchestrator-ssl-1
          - name: LOG_LEVEL
            value: Info
          # Uncomment the next two blocks to use Active Directory authentication
          #- name: USERNAME
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: username
          #- name: PASSWORD
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: password
          # Uncomment the next four blocks to use OAuth authentication (TOKEN_LIFETIME is optional)
          #- name: BEARER_TOKEN_URL
          #  value: https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token
          #- name: TOKEN_LIFETIME
          #  value: "150"
          #- name: CLIENTID
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: clientid
          #- name: CLIENT_SECRET
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: clientsecret

        volumeMounts:
          - mountPath: /etc/ssl/certs/ca-certificates.crt
            name: root-ca
            readOnly: true
            subPath: ca-certificates.crt

      volumes:
        - configMap:
            items:
            - key: ca-certificates.crt
              path: ca-certificates.crt
            name: ca-roots
          name: root-ca

      imagePullSecrets:
        - name: keyregcred

Set the permissions on the deployment file such that the file is owned by root and readable only by root (this assumes your Kubernetes implementation is running as root, which is typical). For example:

sudo chown root:root uo_ssl.yaml

sudo chmod 400 uo_ssl.yaml

Tip: If you need to make edits to the values file, you will need to make it writable again. For example:
sudo chmod 600 uo_ssl.yaml
Execute the following command to install and run the container:

kubectl apply --namespace keyfactor-orchestrators -f uo_ssl.yaml

Tip: To review logs generated from the container, identify the pod name with this command:
kubectl get pods --namespace keyfactor-orchestrators
Then use the following command to output the current log:
kubectl logs --namespace keyfactor-orchestrators [pod name] --follow
The optional follow parameter A parameter or argument is a value that is passed into a function in an application. will continuously output the logs as they are generated until interrupted.
If you need to delete the container and try the install again, use this command:
kubectl delete --namespace keyfactor-orchestrators -f uo_ssl.yaml

Kubernetes Custom Extensions without Helm

To use custom extensions with the orchestrators (see Installing Certificate Store Management Extensions), create a ConfigMap in Kubernetes based on the YAML file containing the extensiondownloader definition shown below. This extension downloader contains a Python script that will retrieve the extension specified in the values file from the Keyfactor GitHub site. This ConfigMap is then mounted into the initContainer, which runs before the main container starts. The initContainer ensures that the required extension is downloaded and placed in the correct directory (e.g. /app/extensions/remote-file-orchestrator) before the orchestrator starts running. This approach decouples extension management from the container image, enabling dynamic updates and consistent deployments.

Tip: For information on installing remote PAM extensions, see Remote PAM Extensions on the Keyfactor Universal Orchestrator Server (Container).

Note: Keyfactor recommends running one extension per Universal Orchestrator container for ease of deployment and maintenance.

To do this:

Create the YAML file and place it in the same directory as the main values.yaml file. Show extension-downloader.yaml file contents.

Tip: Download a copy of the extension-downloader.yaml file.

Copy

extension-downloader.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: extension-downloader-configmap
data:
  install.py: |
    import argparse
    import sys
    import os
    import zipfile
    import tempfile
    import json
    from urllib.request import Request, urlopen
    from urllib.error import URLError, HTTPError

    def main():
        parser = argparse.ArgumentParser(description='Download and extract GitHub release')
        parser.add_argument('--extension', required=True, help='Extension name')
        parser.add_argument('--version', required=True, help='Version number')
        parser.add_argument('--out', required=True, help='Output directory')
        parser.add_argument('--github-token-env', default='GITHUB_TOKEN',
                            help='Environment variable name containing a personal access token, if needed. Default is "GITHUB_TOKEN".')
        parser.add_argument('--asset-name', default=None,
                            help='Optional asset filename to match exactly. Defaults to "<extension>_<version>.zip" if not provided.')
        args = parser.parse_args()

        # Build default asset name if not specified
        if not args.asset_name:
            args.asset_name = f"{args.extension}_{args.version}.zip"

        # Ensure output directory exists
        os.makedirs(args.out, exist_ok=True)

        token = os.getenv(args.github_token_env, "")
        headers = {
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        }
        if token:
            headers["Authorization"] = f"Bearer {token}"

        # 1) Get the list of releases for the repository
        release_url = f"https://api.github.com/repos/Keyfactor/{args.extension}/releases"
        print(f"Fetching releases for: {release_url}")
        try:
            req = Request(release_url, headers=headers)
            with urlopen(req) as response:
                if response.status != 200:
                    print(f"Error: Received status code {response.status} from {release_url}", file=sys.stderr)
                    sys.exit(1)
                data = response.read()
                releases = json.loads(data)
        except HTTPError as e:
            print(f"Error fetching release list from {release_url}: {e}", file=sys.stderr)
            sys.exit(1)
        except URLError as e:
            print(f"Connection error while trying to reach {release_url}: {e}", file=sys.stderr)
            sys.exit(1)

        # 2) Find the release that matches the --version (tag_name)
        release_data = None
        for rel in releases:
            if rel.get('tag_name') == args.version:
                release_data = rel
                break

        if not release_data:
            print(f"No release found with tag_name == {args.version}", file=sys.stderr)
            sys.exit(1)

        # 3) Within that release, find the asset URL corresponding to the best choice.
        assets = release_data.get('assets', [])
        if not assets:
            print(f"No assets found in release tag {args.version}", file=sys.stderr)
            sys.exit(1)

        net8_asset = None
        fallback_asset = None

        for asset in assets:
            asset_name = asset.get('name', '')
            print(f"Found asset: {asset_name}")  # For debugging: show all asset names

            # Check if asset name includes 'net8.0' (case-insensitive to be safe)
            if 'net8.0' in asset_name.lower():
                net8_asset = asset
            else:
                if fallback_asset is None:
                    fallback_asset = asset

        # Prefer net8.0 if present, otherwise pick the first fallback
        chosen_asset = net8_asset if net8_asset else fallback_asset
        if not chosen_asset:
            print(f"No suitable asset found (net8.0 or otherwise) in release {args.version}", file=sys.stderr)
            sys.exit(1)

        asset_url = chosen_asset.get('url')
        if not asset_url:
            print(f"No 'url' found in chosen asset for release {args.version}", file=sys.stderr)
            sys.exit(1)

        print(f"Chosen asset: {chosen_asset['name']} ({asset_url})")

        # 4) Download the asset to a temporary directory
        with tempfile.TemporaryDirectory() as tmpdirname:
            local_zip = os.path.join(tmpdirname, args.asset_name)
            print(f"Downloading to {local_zip}...")

            # Update headers to download octet stream
            dl_headers = headers.copy()
            dl_headers['Accept'] = "application/octet-stream"

            try:
                dl_req = Request(asset_url, headers=dl_headers)
                with urlopen(dl_req) as dl_response:
                    if dl_response.status != 200:
                        print(f"Error: Received status code {dl_response.status} when downloading asset from {asset_url}", file=sys.stderr)
                        sys.exit(1)

                    # Write in chunks
                    with open(local_zip, 'wb') as f:
                        chunk_size = 8192
                        while True:
                            chunk = dl_response.read(chunk_size)
                            if not chunk:
                                break
                            f.write(chunk)
            except HTTPError as e:
                print(f"Error downloading asset from {asset_url}:\n{e}", file=sys.stderr)
                sys.exit(1)
            except URLError as e:
                print(f"Connection error while trying to download {asset_url}: {e}", file=sys.stderr)
                sys.exit(1)

            # 5) Extract to output directory
            print(f"Extracting {local_zip} into {args.out}...")
            with zipfile.ZipFile(local_zip, 'r') as zip_ref:
                # Normalize all filenames to use forward slashes
                normalized_names = [name.replace('\\', '/') for name in zip_ref.namelist()]
                # Find common prefix (root directory if the zip has one)
                common_prefix = os.path.commonprefix(normalized_names)
                if not common_prefix.endswith('/'):
                    common_prefix = os.path.dirname(common_prefix) + '/'
                prefix_length = len(common_prefix)

                # Extract each member, stripping out the common prefix
                for member in zip_ref.infolist():
                    original_name = member.filename.replace('\\', '/')
                    relative_path = original_name[prefix_length:]
                    member.filename = relative_path
                    zip_ref.extract(member, args.out)

        print(f"Extraction complete. Files are in {args.out}.")

    if __name__ == '__main__':
        main()

Create the ConfigMap from the extension-downloader.yaml file. For example:

sudo kubectl apply --namespace keyfactor-orchestrators -f extension-downoader.yaml

Update your Kubernetes deployment file (e.g. uo_ext.yaml) in the directory for your Kubernetes container similar to the following, using the inputs as per Table 1035: Linux Container Parameters for Kubernetes without Helm, referencing the artifactory for the non-ssl image. The fields highlighted in red below indicate fields that need to be edited or that you may wish to edit. Fields highlighted in yellow indicate fields that are added to support the extension.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  # Give the pod a unique name if you plan to deploy more than one orchestrator to the same Kubernetes server or cluster
  name: keyfactor-uo-1
  labels:
    app.kubernetes.io/name: keyfactor-universal-orchestrator
    app.kubernetes.io/instance: ext-1
    app.kubernetes.io/version: "25.2"
spec:
  # The universal orchestrator should not have replicas; instead use many different deployments with different names if horizontal scaling is needed
  serviceName: keyfactor-uo-service
  replicas: 1

  selector:
    matchLabels:
      app.kubernetes.io/name: keyfactor-universal-orchestrator
      app.kubernetes.io/instance: ext-1

  template:
    metadata:
      labels:
        app.kubernetes.io/name: keyfactor-universal-orchestrator
        app.kubernetes.io/instance: ext-1

    spec:
      initContainers:
        # The below block provides an example of adding a custom extension
        - command:
          - /bin/sh
          - -c
          - python /tmp/install.py --extension remote-file-orchestrator --version 2.11.2
            --out /app/extensions/remote-file-orchestrator
          image: python:3.11.10
          imagePullPolicy: IfNotPresent
          name: extensiondownloader
          resources: {}
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
          volumeMounts:
          - mountPath: /tmp
            name: extensiondownloader
          - mountPath: /app/extensions/remote-file-orchestrator
            name: plugin
      containers:
        - name: keyfactor-universal-orchestrator-ext-1
        # Extensions are only supported using the non-ssl image
        image: "repo.keyfactor.com/images/command/universal-orchestrator:25.2"
        imagePullPolicy: IfNotPresent
        # Universal orchestrator environment

        env:
          # The below block is the URL of the orchestrator API on the Keyfactor Command server
          - name: COMMAND_AGENTS_URL
            value: https://keyfactor.keyexample.com/KeyfactorAgents
          # The below block is the name the orchestrator will use when registering with Keyfactor Command
          - name: ORCHESTRATOR_NAME
            value: k8s-universal-orchestrator-ext-1
          - name: LOG_LEVEL
            value: Info
          # Uncomment the next two blocks to use Active Directory authentication
          #- name: USERNAME
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: username
          #- name: PASSWORD
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: password
          # Uncomment the next four blocks to use OAuth authentication (TOKEN_LIFETIME is optional)
          #- name: BEARER_TOKEN_URL
          #  value: https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token
          #- name: TOKEN_LIFETIME
          #  value: "150"
          #- name: CLIENTID
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: clientid
          #- name: CLIENT_SECRET
          #  valueFrom:
          #    secretKeyRef:
          #      name: uo-credentials
          #      key: clientsecret

        volumeMounts:
          - mountPath: /etc/ssl/certs/ca-certificates.crt
            name: root-ca
            readOnly: true
            subPath: ca-certificates.crt
          - mountPath: /app/extensions/remote-file-orchestrator
            name: plugin
            readOnly: false

      volumes:
        - configMap:
            items:
            - key: ca-certificates.crt
              path: ca-certificates.crt
            name: ca-roots
          name: root-ca
        - configMap:
            defaultMode: 420
            name: extension-downloader-configmap
          name: extensiondownloader
        - emptyDir: {}
          name: plugin

      imagePullSecrets:
        - name: keyregcred

Execute the following command to install and run the container:

sudo kubectl apply --namespace keyfactor-orchestrators -f uo_ext.yaml

Table 1035: Linux Container Parameters for Kubernetes without Helm

Parameter	Description
AppSettings__CheckServerCertificateRevocation	A Boolean that indicates whether the revocation status (CRL) of the SSL certificate on the Keyfactor Command server should be checked when connecting to Keyfactor Command (true) or not (false). The default is true (CRL checking will be done).
AUDIENCE	This parameter is used to specify an audience value to be included in token requests delivered to the identity provider when using an identity provider other than Active Directory.
BEARER_TOKEN_URL	Required^*. The URL of the token endpoint for your identity provider. For example: Copy `https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token` For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation). This parameter is required if you’re using an identity provider other than Active Directory.
CLIENTID	Required^*. For implementations using an identity provider other than Active Directory, the ID of the identity provider client that should be used to authenticate the session (see Create Service Accounts for the Universal Orchestrator). This parameter is required if you’re using an identity provider other than Active Directory.
CLIENT_SECRET	Required^*. For implementations using an identity provider other than Active Directory, the secret of the identity provider client that should be used to authenticate the session. This parameter is required if you’re using an identity provider other than Active Directory.
COMMAND_AGENTS_URL	Required. The URL of the Orchestrators API on the Keyfactor Command server. For example: Copy `https://keyfactor.keyexample.com/KeyfactorAgents`
LOG_LEVEL	The logging level for the orchestrator. The default value is Info. Possible values are the same as those described in Configure Logging for the Universal Orchestrator.
ORCHESTRATOR_NAME	The name the orchestrator uses to register itself with Keyfactor Command. By default, the container hostname is used, which is not ideal as this will create a new orchestrator entry with every container start. Although this parameter is not strictly required, Keyfactor strongly recommends using it. If you choose to uninstall and reinstall the orchestrator (e.g. using compose down), it is important to use the same orchestrator name for subsequent implementations so that Keyfactor Command will recognize the orchestrator when it is started again.
PASSWORD	Required^*. The password for the Keyfactor Command Connect Service Account if you’re using Active Directory as an identity provider (see USERNAME). This parameter is required if you’re using Active Directory as an identity provider.
SCOPE	This parameter is used to specify one or more scopes that should be included in token requests delivered to the identity provider when using an identity provider other than Active Directory. Multiple scopes should be separated by spaces.
TOKEN_LIFETIME	For implementations using an identity provider other than Active Directory, the number of seconds for which the bearer token is valid. If not specified, the orchestrator uses the default value set by the Keyfactor Command server of 300 seconds (5 minutes).
USERNAME	Required^*. The username for service account used to connect to the Keyfactor Command server (see PASSWORD). This is the Keyfactor Command Connect Service Account described in Create Service Accounts for the Universal Orchestrator if you’re using Active Directory as an identity provider. The orchestrator uses Basic Authentication to authenticate to Keyfactor Command. This parameter is required if you’re using Active Directory as an identity provider.

Kubernetes with Helm

To deploy the container under Kubernetes managed with a Helm chart:

Create a directory from which you will run the container (e.g. /opt/kyf_uo).
If desired, create a namespace for Universal Orchestrator resources and containers in Kubernetes. For example:

sudo kubectl create namespace keyfactor-orchestrators
Create a secret in Kubernetes to allow the Universal Orchestrator to authenticate to Keyfactor Command (see Create Service Accounts for the Universal Orchestrator).

For example, for Active Directory authentication:

sudo kubectl create secret generic uo-credentials --namespace keyfactor-orchestrators --from-literal=username=KEYEXAMPLE\svc_kyforch --from-literal=password=MySuperSecretPassword

For OAuth authentication:

sudo kubectl create secret generic client-credentials --namespace keyfactor-orchestrators --from-literal=clientid=Universal-Orchestrator --from-literal=clientsecret=MySuperSecretClientSecret
Create a secret in Kubernetes for the credentials you will use to authenticate to the Keyfactor artifactory. For example:

kubectl create secret docker-registry keyregcred --namespace keyfactor-orchestrators --docker-server=repo.keyfactor.com --docker-username=MyUsername --docker-password=MySuperSecretToken --docker-email=my.email@my-domain.com

Note: For artifactory credentials or more information, check with your Keyfactor Client Success Manager or contact support@keyfactor.com.
Create a ConfigMap in Kubernetes containing CA root and issuing certificates for all CAs in the environment that will have any relationship with the Universal Orchestrator (see Configure Certificate Root Trust for the Universal Orchestrator).

Once the host’s trust store is updated with all the certificates you will need, create the ConfigMap. For example:

sudo kubectl create configmap ca-roots --namespace keyfactor-orchestrators --from-file=/etc/ssl/certs/ca-certificates.crt

Note: The standard path to the trusted root store will vary depending on your Linux implementation.

The Universal Orchestrator ships with a helm chart that contains most of the configuration needed to get up and running, but a few additional pieces of information are needed. These are provided via a separate values file that feeds into the helm chart so that the actual helm chart does not need to be edited. See the below values file. Some fields in this file are required, and others are optional.

Create an input file to the helm chart similar to the following, using the inputs as per Table 1036: Universal Orchestrator Containerized Installation Values File Settings. Use a text editor to update the file, based on the below sample. For example:

nano /opt/kyf_uo/values.yaml

The fields highlighted in red below indicate fields that need to be edited or that you may wish to edit. The fields highlighted in green indicate data provided with secrets or config maps created previously.

image:
  # Uncomment the desired image and confirm correct artifactory and version
  repository: "repo.keyfactor.com/images/command/universal-orchestrator-ssl"
  #repository: "repo.keyfactor.com/images/command/universal-orchestrator"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  #tag: "25.2"

imagePullSecrets:
  - name: keyregcred

orchestrator:
  commandUrl: "https://command.keyexample.com/KeyfactorAgents"
  checkCrl: true
  # The below value is the name the orchestrator will use when registering with Keyfactor Command
  name: "universal-orchestrator-1"
  logLevel: Info
  auth:
    useAD: true
    # Uncomment the oauth section and set useAD to false to use OAuth authentication
    #oauth:
    #  secretName: client-credentials
    #  secretClientIdKey: client-id
    #  secretClientSecretKey: client-secret
    #  tokenUrl: ""
    #  audience: ""
    #  scope: ""
    # Uncomment the ad section and set useAD to true to use Active Directory authentication
    #ad:
    #  secretName: uo-credentials
    #  secretUsernameKey: username
    #  secretPasswordKey: password

volumeMounts:
  - mountPath: /etc/ssl/certs/ca-certificates.crt
    name: root-ca
    readOnly: true
    subPath: ca-certificates.crt

volumes:
  - configMap:
      name: ca-roots
      items:
      - key: ca-certificates.crt
        path: ca-certificates.crt
    name: root-ca

initContainers:
  # See separate section for example of adding a custom extension

podSecurityContext:
runAsNonRoot: true
runAsUser: 1000

Set the permissions on the values file such that the file is owned by root and readable only by root (this assumes your Kubernetes implementation is running as root, which is typical). For example:

sudo chown root:root values.yaml

sudo chmod 400 /values.yaml

Tip: If you need to make edits to the values file, you will need to make it writable again. For example:
sudo chmod 600 values.yaml
Login to the JFrog repository so that you may retrieve the helm chart. For example:

sudo helm registry login repo.keyfactor.com --password YouSuperSecretRepoAPIKeyorToken --username YourRepoUsername

Confirm that login completes successfully.
Run the install, giving the deployment a name and referencing your customized values file. For example:

sudo helm install Helm_Deployment_Name --namespace keyfactor-orchestrators --values values.yaml oci://repo.keyfactor.com/charts/command/universal-orchestrator --version 1.0.0

Tip: To review logs generated from the container, identify the pod name with this command:

sudo kubectl get pods -A | grep orchestrator

For the Universal Orchestrator container. For example:

Helm_Deployment_Name-universal-orchestrator-instance

For example:

ssl-universal-orchestrator-0

Then use the following command to output the current log:

sudo kubectl logs --namespace keyfactor-orchestrators ssl-universal-orchestrator-0 --follow

The optional follow parameter will continuously output the logs as they are generated until interrupted.

If no log output is being generated, this may indicate a failure is occurring earlier in the process during container creation. If that’s the case, the following command to output details for the container may be helpful. Again, the commend references the name of the container. For example:

sudo kubectl describe --namespace keyfactor-orchestrators pods/ssl-universal-orchestrator-0

If you need to delete the install and try again, use this command:

sudo helm uninstall Helm_Deployment_Name --namespace keyfactor-orchestrators

Kubernetes Custom Extensions with Helm

Tip: For information on installing remote PAM extensions, see Remote PAM Extensions on the Keyfactor Universal Orchestrator Server (Container).

Note: Keyfactor recommends running one extension per Universal Orchestrator container for ease of deployment and maintenance.

To do this:

Create the YAML file and place it in the same directory as the main values.yaml file. Show extension-downloader.yaml file contents.

Tip: Download a copy of the extension-downloader.yaml file.

Copy

extension-downloader.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: extension-downloader-configmap
data:
  install.py: |
    import argparse
    import sys
    import os
    import zipfile
    import tempfile
    import json
    from urllib.request import Request, urlopen
    from urllib.error import URLError, HTTPError

    def main():
        parser = argparse.ArgumentParser(description='Download and extract GitHub release')
        parser.add_argument('--extension', required=True, help='Extension name')
        parser.add_argument('--version', required=True, help='Version number')
        parser.add_argument('--out', required=True, help='Output directory')
        parser.add_argument('--github-token-env', default='GITHUB_TOKEN',
                            help='Environment variable name containing a personal access token, if needed. Default is "GITHUB_TOKEN".')
        parser.add_argument('--asset-name', default=None,
                            help='Optional asset filename to match exactly. Defaults to "<extension>_<version>.zip" if not provided.')
        args = parser.parse_args()

        # Build default asset name if not specified
        if not args.asset_name:
            args.asset_name = f"{args.extension}_{args.version}.zip"

        # Ensure output directory exists
        os.makedirs(args.out, exist_ok=True)

        token = os.getenv(args.github_token_env, "")
        headers = {
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        }
        if token:
            headers["Authorization"] = f"Bearer {token}"

        # 1) Get the list of releases for the repository
        release_url = f"https://api.github.com/repos/Keyfactor/{args.extension}/releases"
        print(f"Fetching releases for: {release_url}")
        try:
            req = Request(release_url, headers=headers)
            with urlopen(req) as response:
                if response.status != 200:
                    print(f"Error: Received status code {response.status} from {release_url}", file=sys.stderr)
                    sys.exit(1)
                data = response.read()
                releases = json.loads(data)
        except HTTPError as e:
            print(f"Error fetching release list from {release_url}: {e}", file=sys.stderr)
            sys.exit(1)
        except URLError as e:
            print(f"Connection error while trying to reach {release_url}: {e}", file=sys.stderr)
            sys.exit(1)

        # 2) Find the release that matches the --version (tag_name)
        release_data = None
        for rel in releases:
            if rel.get('tag_name') == args.version:
                release_data = rel
                break

        if not release_data:
            print(f"No release found with tag_name == {args.version}", file=sys.stderr)
            sys.exit(1)

        # 3) Within that release, find the asset URL corresponding to the best choice.
        assets = release_data.get('assets', [])
        if not assets:
            print(f"No assets found in release tag {args.version}", file=sys.stderr)
            sys.exit(1)

        net8_asset = None
        fallback_asset = None

        for asset in assets:
            asset_name = asset.get('name', '')
            print(f"Found asset: {asset_name}")  # For debugging: show all asset names

            # Check if asset name includes 'net8.0' (case-insensitive to be safe)
            if 'net8.0' in asset_name.lower():
                net8_asset = asset
            else:
                if fallback_asset is None:
                    fallback_asset = asset

        # Prefer net8.0 if present, otherwise pick the first fallback
        chosen_asset = net8_asset if net8_asset else fallback_asset
        if not chosen_asset:
            print(f"No suitable asset found (net8.0 or otherwise) in release {args.version}", file=sys.stderr)
            sys.exit(1)

        asset_url = chosen_asset.get('url')
        if not asset_url:
            print(f"No 'url' found in chosen asset for release {args.version}", file=sys.stderr)
            sys.exit(1)

        print(f"Chosen asset: {chosen_asset['name']} ({asset_url})")

        # 4) Download the asset to a temporary directory
        with tempfile.TemporaryDirectory() as tmpdirname:
            local_zip = os.path.join(tmpdirname, args.asset_name)
            print(f"Downloading to {local_zip}...")

            # Update headers to download octet stream
            dl_headers = headers.copy()
            dl_headers['Accept'] = "application/octet-stream"

            try:
                dl_req = Request(asset_url, headers=dl_headers)
                with urlopen(dl_req) as dl_response:
                    if dl_response.status != 200:
                        print(f"Error: Received status code {dl_response.status} when downloading asset from {asset_url}", file=sys.stderr)
                        sys.exit(1)

                    # Write in chunks
                    with open(local_zip, 'wb') as f:
                        chunk_size = 8192
                        while True:
                            chunk = dl_response.read(chunk_size)
                            if not chunk:
                                break
                            f.write(chunk)
            except HTTPError as e:
                print(f"Error downloading asset from {asset_url}:\n{e}", file=sys.stderr)
                sys.exit(1)
            except URLError as e:
                print(f"Connection error while trying to download {asset_url}: {e}", file=sys.stderr)
                sys.exit(1)

            # 5) Extract to output directory
            print(f"Extracting {local_zip} into {args.out}...")
            with zipfile.ZipFile(local_zip, 'r') as zip_ref:
                # Normalize all filenames to use forward slashes
                normalized_names = [name.replace('\\', '/') for name in zip_ref.namelist()]
                # Find common prefix (root directory if the zip has one)
                common_prefix = os.path.commonprefix(normalized_names)
                if not common_prefix.endswith('/'):
                    common_prefix = os.path.dirname(common_prefix) + '/'
                prefix_length = len(common_prefix)

                # Extract each member, stripping out the common prefix
                for member in zip_ref.infolist():
                    original_name = member.filename.replace('\\', '/')
                    relative_path = original_name[prefix_length:]
                    member.filename = relative_path
                    zip_ref.extract(member, args.out)

        print(f"Extraction complete. Files are in {args.out}.")

    if __name__ == '__main__':
        main()

Create the ConfigMap from the extension-downloader.yaml file. For example:

sudo kubectl apply --namespace keyfactor-orchestrators -f extension-downoader.yaml

Update the custom values file for your orchestrator as shown in the below example.

nano /opt/kyf_uo/values.yaml

image:
  # Extensions are only supported using the non-ssl image
  repository: "repo.keyfactor.com/images/command/universal-orchestrator"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  #tag: "25.2"

imagePullSecrets:
  - name: keyregcred

orchestrator:
  commandUrl: "https://command.keyexample.com/KeyfactorAgents"
  checkCrl: true
  # The below value is the name the orchestrator will use when registering with Keyfactor Command
  name: "universal-orchestrator-1"
  logLevel: Trace
  auth:
    useAD: true
    # Uncomment the oauth section and set useAD to false to use OAuth authentication
    #oauth:
    #  secretName: client-credentials
    #  secretClientIdKey: client-id
    #  secretClientSecretKey: client-secret
    #  tokenUrl: ""
    #  audience: ""
    #  scope: ""
    # Uncomment the ad section and set useAD to true to use Active Directory authentication
    #ad:
    #  secretName: uo-credentials
    #  secretUsernameKey: username
    #  secretPasswordKey: password

volumeMounts:
  - mountPath: /app/extensions/remote-file-orchestrator
    name: plugin
  - mountPath: /etc/ssl/certs/ca-certificates.crt
    name: root-ca
    readOnly: true
    subPath: ca-certificates.crt

volumes:
  - configMap:
      defaultMode: 420
      name: extension-downloader-configmap
    name: extensiondownloader
  - emptyDir: {}
    name: plugin
  - configMap:
      name: ca-roots
      items:
      - key: ca-certificates.crt
        path: ca-certificates.crt
    name: root-ca

initContainers:
  - command:
    - /bin/sh
    - -c
    - python /tmp/install.py --extension remote-file-orchestrator --version 2.11.2
      --out /app/extensions/remote-file-orchestrator
    image: python:3.11.10
    imagePullPolicy: IfNotPresent
    name: extensiondownloader
    resources: {}
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    volumeMounts:
    - mountPath: /tmp
      name: extensiondownloader
    - mountPath: /app/extensions/remote-file-orchestrator
      name: plugin

podSecurityContext:
runAsNonRoot: true
runAsUser: 1000

Load the new values, referencing the deployment name, namespace, your customized values file, the helm chart, and version. For example:

sudo helm upgrade Helm_Deployment_Name --namespace keyfactor-orchestrators --values values.yaml oci://repo.keyfactor.com/charts/command/universal-orchestrator --version 1.0.0

Note: The Keyfactor Universal Orchestrator running in a container does not support client certificate authentication.

Tip: Once the installation of the orchestrator is complete, you need to use the Keyfactor CommandManagement Portal to approve the orchestrator and configure certificate stores or SSL jobs:

Was this page helpful? Provide Feedback

Version v25.2

On this page: