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.

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 Universal Orchestrator image from the artifactory with commands similar to the following (placing the token or API 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 provided to you by Keyfactor in the my_password file):

   sudo nano my_password.txt
   cat my_password.txt | docker login keyexample.jfrog.io --username username --password-stdin
   docker pull keyexample.jfrog.io/keyexample/command/universal-orchestrator-ssl:11.2
   Note:  The image artifactory will be available soon. For 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

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 859: 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: keyexample.jfrog.io/keyexample/command/universal-orchestrator-ssl:11.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:/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

   For example, in the following output you could select either the container ID 0cf41b4c1ca4 or the name kyfidp:

   CONTAINER ID   IMAGE                                                    COMMAND                  CREATED        STATUS        PORTS                                                        NAMES
   b2abfe2b2b92   art.example1.com/condev-con/ejbca/ejbca-proxy:8.2.0      "/opt/keyfactor/bin/…"   2 months ago   Up 2 months   8009/tcp, 8081-8082/tcp, :::80->8080/tcp, :::443->8443/tcp   ejbca82
   ee461eb238ba   mariadb:latest                                           "docker-entrypoint.s…"   2 months ago   Up 2 months   0.0.0.0:3306->3306/tcp, :::3306->3306/tcp                    ejbca81-database
   0cf41b4c1ca4   art.example2.com/condev-exam/command/auth-server:latest  "/opt/kyfidp/bin/k…"     3 months ago   Up 3 months   8080/tcp, 0.0.0.0:5443->8443/tcp, :::5443->8443/tcp          kyfidp

   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/kyfuseng-release/command/universal-orchestrator:11.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.

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 authentication with an identity provider other than Active Directory:

   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=keyexample.jfrog.io --docker-username=MyUsername --docker-password=MySuperSecretAPIKeyorToken --docker-email=my.email@my-domain.com
   Note:  The image artifactory will be available soon. For more information, check with your Keyfactor Client Success Manager or contact support@keyfactor.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 859: 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.2"
   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: example/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: example/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 and add correct artifactory
           image: "keyexample.jfrog.io/keyexample/command/universal-orchestrator-ssl:11.2"
           #image: "keyexample.jfrog.io/keyexample/command/universal-orchestrator:11.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:
             # 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