Documentation Suite v25.1

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 can be found in the following JFrog repository:

repo.keyfactor.com/images/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.

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:

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 1026: Linux Container Parameters, 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.

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.

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.1"
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.1"
        #image: "repo.keyfactor.com/images/command/universal-orchestrator:25.1"
        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 Custom-Built 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.

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. 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 1026: Linux Container Parameters, 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.1"
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.9.1
            --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.1"
        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

Kubernetes with Helm

To deploy the container under Kubernetes and is 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 1027: 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/charts/command/universal-orchestrator-ssl"
  #repository: "repo.keyfactor.com/charts/command/universal-orchestrator"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  #tag: "25.1"

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

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. 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/charts/command/universal-orchestrator"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  #tag: "25.1"

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.9.1
      --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

Execute the following command to install and run the container:

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

Table 1026: Linux Container Parameters

Parameter	Description
App Settings__ Check Server Certificate Revocation	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 Keyfactor Identity Provider, 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 Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). This parameter is required if you’re using an identity provider other than Active Directory.
CLIENT ID	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.

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:

Version v25.1

On this page: