Install the Universal Orchestrator in a Linux Container

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:

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

2. Select a Universal Orchestrator image, and from your Docker host, retrieve the Keyfactor Identity Provider image from the artifactory with commands similar to the following (using credentials provided to you by Keyfactor; the password is saved in my_password.txt):

   cat my_password.txt | docker login keyfactor.jfrog.io --username username --password-stdin
   docker pull keyfactor.jfrog.io/con-develop-us-engineering/command/universal-orchestrator-ssl:11.0
   Important:  Remove the my_password.txt file when complete.

3. Create a Docker compose file (compose.yaml) in the directory for your Docker container similar to the following, using the inputs as per Table 825: Linux Container Parameters, referencing the artifictory you pulled, selecting the appropriate authentication mechanism for your environment, and any additional volume mounts (see Custom Extensions). 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 found. 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: keyfactor.jfrog.io/con-develop-us-engineering/command/universal-orchestrator-ssl:11.0
       container_name: universal_orchestrator_1
       environment:
         COMMAND_AGENTS_URL: https://keyfactor.keyexample.com/KeyfactorAgents
         ORCHESTRATOR_NAME: appsrvr19-UO-1
   
         # Uncomment the next two lines to use Active Directory
         #USERNAME: KEYEXAMPLE\svc_kyforch
         #PASSWORD: MySuperSecretPassword
         
         # Uncomment the next two lines to use Keyfactor Identity Provider
         #BEARER_TOKEN_URL: https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token
         #TOKEN_LIFETIME=300
         #CLIENTID: Universal-Orchestrator
         #CLIENT_SECRET: Client-Secret-from-Keyfactor-IdP
       volumes:
         - /etc/ssl/certs:/etc/ssl/certs:ro

   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.

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

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

   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

To use custom extensions with the orchestrators (see Installing Custom-Built 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.

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

1. 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).

2. 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:/etc/ssl/certs:ro
         - /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:

1. 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).

2. 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 keyfactor.jfrog.io/con-develop-us-engineering/command/universal-orchestrator:11.0
   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.

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

4. 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]

5. Complete the install as above.

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

1. Create a directory from which you will run the container (e.g. /opt/kyf_uo).

2. Create a secret in Kubernetes for the credentials that the orchestrator(s) will use to authenticate to Keyfactor Command (see Create Service Accounts for the Universal Orchestrator). For example, for Active Directory authentication:

   echo -n 'keyexample\svc_kyforch' > ./username
   echo -n 'MySuperSecretPassword' > ./password
   kubectl create secret generic uo-credentials --from-file=./username --from-file=./password

   For Keyfactor Identity Provider authentication:

   echo -n 'Universal-Orchestrator' > ./clientid
   echo -n 'Client-Secret-from-Keyfactor-IdP' > ./clientsecret
   kubectl create secret generic uo-credentials --from-file=./clientid --from-file=./clientsecret
   Important:  The password or secret for the Keyfactor Command connect service account is stored in clear text in the “password” or “clientsecret” file. Be sure to delete it after the Kubernetes secret has been created.

3. 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 --docker-server=keyfactor.jfrog.io --docker-username=MyUsername --docker-password=MySuperSecretPassword --docker-email=my.email@my-domain.com

4. On your Kubernetes server, create a configmap 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 certificates, including the chain certificates for the SSL certificate on the Keyfactor Command server (see Configure Certificate Root Trust for the Universal Orchestrator). For example:

   kubectl create configmap ca-roots --from-file=/etc/ssl/certs/ca-certificates.crt
   Note:  The standard path to the trusted root store will vary depending on your Linux implementation.

5. 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 825: Linux Container Parameters, referencing the artifictory 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 found. 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: "11.0"
   spec:
     # The universal orchestrator should not have replicas; instead use many different deployments with different names if horizontal scaling is needed
     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:
           # The below two commented out blocks provide examples of adding custom extensions
           #- env:
           #  - name: EXTENSION_NAME
           #    value: citrix-adc-orchestrator
           #  - name: EXTENSION_VERSION
           #    value: 2.0.0
           #  - name: INSTALL_PATH
           #    value: /app/extensions/citrix-adc-orchestrator
           #  image: m8rmclarenkf/uo_extension_installer:1.0.5
           #  imagePullPolicy: IfNotPresent
           #  name: citrix-adc-orchestrator-installer
           #  volumeMounts:
           #  - mountPath: /app/extensions
           #    name: command-pv-claim
           #    readOnly: false
           #    subPath: ""
           #- env:
           #  - name: EXTENSION_NAME
           #    value: f5-rest-orchestrator
           #  - name: EXTENSION_VERSION
           #    value: 1.4.4
           #  - name: INSTALL_PATH
           #    value: /app/extensions/f5-rest-orchestrator
           #  image: m8rmclarenkf/uo_extension_installer:1.0.5
           #  imagePullPolicy: IfNotPresent
           #  name: f5-rest-orchestrator-installer
           #  volumeMounts:
           #  - mountPath: /app/extensions
           #    name: command-pv-claim
           #    readOnly: false
           #    subPath: ""
         containers:
           - name: keyfactor-universal-orchestrator-ssl-1
             # Uncomment the desired image
             image: "keyfactor.jfrog.io/con-develop-us-engineering/command/universal-orchestrator-ssl:11.0"
             #image: "keyfactor.jfrog.io/con-develop-us-engineering/command/universal-orchestrator:11.0"
             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 Keyfactor Identity Provider (OAuth) authentication
               #- name: BEARER_TOKEN_URL
               #  value: https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token
               #- name: TOKEN_LIFETIME
               #  value: "300"
               #- name: CLIENTID
               #  valueFrom:
               #    secretKeyRef:
               #      name: uo-credentials
               #      key: clientid
               #- name: CLIENT_SECRET
               #  valueFrom:
               #    secretKeyRef:
               #      name: uo-credentials
               #      key: clientsecret
             volumeMounts:
               # Uncomment the next block if adding extensions
               #- mountPath: /app/extensions
               #  name: command-pv-claim
               #  readOnly: false
               #  subPath: ""
               - mountPath: /etc/ssl/certs/ca-certificates.crt
                 name: root-ca
                 readOnly: false
                 subPath: ca-certificates.crt
         volumes:
           - configMap:
               items:
               - key: ca-certificates.crt
                 path: ca-certificates.crt
               name: ca-roots
             name: root-ca
           # Uncomment the next block if adding extensions
           #- name: command-pv-claim
           #  emptyDir: {}
         imagePullSecrets:
           - name: keyregcred

6. 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 compose file, you will need to make the file writable again. For example:

   sudo chmod 600 uo_ssl.yaml

7. Execute the following command to install and run the container:

   kubectl apply -f uo_ssl.yaml
   Tip:   To review logs generated from the container, identify the pod name with this command:

   kubectl get pods

   Then use the following command to output the current log:

   kubectl logs [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 -f uo_ssl.yaml