Installing a remote worker as a root user

Edit online

You can run workflows from a remote host by installing a remote worker as a user that has root privileges.

You can install a remote worker as a root user by using any of these methods:
  • Installing it on a VM on a K3s cluster.
  • Installing it on a VM via Docker Compose or Podman Compose.
  • Installing it on a Kubernetes cluster (such as an OpenShift Container Platform (OCP) or Amazon Elastic Kubernetes Service (EKS) cluster).
Important: The required steps to upgrade a remote worker are the same as the required steps to install a remote worker. To upgrade a remote worker, verify that the prerequisites are in place, then follow the installation steps that apply for your environment.
The remote worker installation package is available in two forms:
  1. A stand-alone remote worker package for x86 architecture that includes the required images to run the worker.
    • In the stand-alone remote worker package, the images are contained in an embedded file. By default, they are loaded from the embedded file into your container runtime.
  2. A standard remote worker package that is part of the Concert x86 software package.
    • In the standard remote worker package, the images are not included. You must load them from an image registry.
Tip:
Consider which installation package type is most suitable for your installation scenario.
  • A stand-alone package is suitable in these scenarios:
    • The remote host is air-gapped.
    • The remote host does not have a configured cluster.
    • You are not required to download the remote worker images from IBM Container Registry during installation.
  • A standard Concert package is suitable when a K3s, OCP, or EKS cluster runs on the remote host and you want to download the images from IBM Container Registry during installation.
When you run the remote worker installation script (install_rw.sh), you must provide this information:
  • The name of the host where Concert Workflows runs.
  • The name and secret of the Concert Workflows worker group that you want to connect the remote worker to.

You can also specify additional values, such as which container runtime to use (Docker, Podman, or a native K3s or Kubernetes container runtime) and which image source to use (the embedded file or an image registry).

To see all available usage options, run the script with only the --help option specified, for example: ./bin/install_rw.sh --help

Before you begin

Note: In this topic, the term remote host refers to the host on which you run the remote worker installation script.
  • If you intend to run the installation script on a VM, the remote host is the VM.
  • If you intend to install the remote worker on a K3s, OCP, or EKS cluster, the remote host must be logged in to the cluster.
  • The hardware resource and operating system recommendations in this topic apply only to the remote host.
  • Make sure that the following hardware resources are available on the remote host:
    • 2 virtual CPUs (vCPUs).
    • 4 GB of RAM.
    • 30 GB of disk space.
    • 1 Gb/s of network interface speed.
  • Only the following operating systems are supported for remote hosts:
    • Red Hat Enterprise Linux (RHEL) 9 (or later versions).
    • Ubuntu 24 (or a later version).
  • The remote host must be able to communicate with your Concert Workflows instance. Check your network configuration and ensure that the remote host can communicate by using both the HTTP and WebSocket protocols with port 443 on the host where Concert Workflows runs.
  • If you intend to load the remote worker images from IBM Container Registry when you install, complete these steps:
    1. Get an IBM entitlement key. You must have an IBMid to obtain an entitlement key. For more information, see Obtaining an IBM entitlement API key.
    2. In your network configuration, ensure that the remote host can communicate by using both the HTTP and WebSocket protocols with IBM Container Registry (cp.icr.io).
  • In the Concert Workflows UI, create a worker group. In the sidebar, click Worker groups, then click + Create worker group and provide the necessary values.
    Note: In the dialog, copy the following values, because you need them to install the remote worker:
    • The highlighted Concert Workflows server hostname.
    • The name of the new group.
    • The value of the new group’s secret.
  • Use the following table to determine your installation method:
    Table 1. Recommended installation methods
    Remote environment Remote host operating system Recommended installation method
    VM without configured cluster Red Hat Enterprise Linux (RHEL) 9 (or later versions) Podman Compose
    VM without configured cluster Ubuntu 24 (or a later version) Docker Compose
    VM with lightweight single-node cluster
    • Red Hat Enterprise Linux (RHEL) 9 (or later versions)
    • Ubuntu 24 (or a later version)
    		K3s
    Existing OCP / EKS cluster
    • Red Hat Enterprise Linux (RHEL) 9 (or later versions)
    • Ubuntu 24 (or a later version)
    		Kubernetes

Installing on a VM on a K3s cluster

When you use this installation method, you can load the required container images from either the embedded file or from IBM Container Registry.
Note: This installation method is available only on x86-based architecture. When you install on a VM on a K3s cluster, you must use an x86-based installation package.
Prerequisites
  • Log in to the VM as a user with root privileges and run all commands as this root user.
  • In your VM, install and configure K3s.
    1. Install K3s by running this command: 
      curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION=<K3s-version> sh -s - --write-kubeconfig-mode 644 --disable traefik
      Replace <K3s-version> with a supported K3s version, that is, a version between v1.29.2+k3s1 and v1.33.x.
    2. Allow the kubectl CLI tool to connect to the K3s cluster by running these commands: 
      echo "export KUBECONFIG=/etc/rancher/k3s/k3s.yaml" >> ~/.bashrc
source ~/.bashrc
    3. If you want to remotely run workflows that use the FaaS integration, update K3s configuration to ensure that the cluster trusts the fully qualified domain name (FQDN) of your VM.
      1. Go to the /etc/rancher/k3s/ folder.
      2. Check whether the folder contains a file that is called registries.yaml. If not, create it.
      3. Edit the registries.yaml file and add this YAML configuration 
        # /etc/rancher/k3s/registries.yaml

configs:
  "<VM_FDQN>": 
    tls: 
       insecure_skip_verify: true
        Replace <VM_FQDN> with the fully qualified domain name (FQDN) of the VM (for example,hostname.domain.com).
    4. Restart the K3s service. 
      sudo systemctl restart k3s
  • Install and configure Helm version 3.x by running these commands: 
    curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
  • Verify that all K3s cluster nodes are ready by running this command: 
    kubectl get nodes
Procedure
  1. Download the remote worker installation package of your choosing.
    • To download the stand-alone package for x86 architecture, click this link.
    • To download the standard Concert package for x86 architecture, run this command: 
      wget https://github.com/IBM/Concert/releases/download/v3.0.0/ibm-concert-x86.tar.gz
  2. Copy the package to your VM file system.
  3. Extract the package.
    • For the stand-alone package, run this command: 
      tar xfz ibm-concert-workflows-rw-x86_64.tar.gz
    • For the standard Concert package, run this command: 
      tar xfz ibm-concert-x86.tar.gz
  4. If you want to load the required images from IBM Container Registry, ensure that your IBM entitlement key will be used as the registry password by running this command: 
    export IBM_REG_PASS=<your-entitlement-key>
    Replace <your-entitlement-key> with your IBM entitlement key.
  5. Go to the folder that contains the remote worker installation script.
    • For the stand-alone package, run this command: 
      cd ./ibm-concert-workflows-rw
    • For the standard Concert package, run this command: 
      cd ./ibm-concert/ibm-concert-std-workflows
  6. Install the remote worker.
    • When you run the installation script, specify where you want to load the images from.
    • If you downloaded a stand-alone package and you want to load the images from the embedded file, run this command:: 
      ./bin/install_rw.sh \
--license-acceptance=y \
--server-hostname=<CW_server_hostname> \
--worker-group-name=<worker_group_name> \
--worker-group-secret-key=<worker_group_secret> \
--target-platform=k3s
    • To load the images from IBM Container Registry, run this command: 
      ./bin/install_rw.sh \
--license-acceptance=y \
--server-hostname=<CW_server_hostname> \
--worker-group-name=<worker_group_name> \
--worker-group-secret-key=<worker_group_secret> \
--target-platform=k3s \
--registry=cp.icr.io \
--registry-user=cp \
--registry-password=$IBM_REG_PASS
    • Replace <CW_server_hostname> with the highlighted Concert Workflows server hostname that you took note of when you created the worker group. To see this host name again, open the Concert Workflows UI, click Worker groups in the sidebar, and open the group that you created. The host name is highlighted in the dialog.
    • Replace <worker_group_name> with the name of the worker group that you created.
    • Replace <worker_group_secret> with the value of the new group’s secret.
  7. Use the kubectl get pods command to monitor the pod statuses. When the pliant-worker pod is running, the remote worker is installed successfully.

Now, when you create a workflow, you can use the new worker group to run it by clicking the Start block in the workflow editor and selecting the new group.

Installing on a VM via Docker Compose or Podman Compose

This method of installing the worker does not require you to set up a cluster.
Note:
  • In this installation method, the remote worker images can be loaded only from the embedded file. It is not possible to load them from an image registry.
  • You can install via Docker Compose only on VMs that use version 24 or later of the Ubuntu operating system.
  • You can install via Podman Compose only on VMs that use version 9 or later of the Red Hat Enterprise Linux (RHEL) operating system.
Prerequisites
  • Log in to the VM as a user with root privileges and run all commands as this root user.
  • If your VM’s operating system is Ubuntu 24 (or a later version), install Docker and Docker Compose.
    1. Edit the Ubuntu package source configuration file by running this command: 
      vim /etc/apt/sources.list.d/ubuntu.sources
    2. In the file, in the Components row, add restricted, universe, and multiverse as repository sources so that the configuration looks similar to this example: 
      Types: deb
URIs: http://us.archive.ubuntu.com/ubuntu/
Suites: noble noble-updates noble-backports
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
    3. Install Docker and Docker Compose by running these commands: 
      apt update
apt install -y docker.io docker-compose-v2
    4. Ensure that the docker daemon is running and enabled to start on boot by running this command: 
      systemctl enable --now docker
  • If your VM’s operating system is RHEL 9 (or a later version), install Podman and Podman Compose.
    1. Install Podman by running this command: 
      dnf install -y podman
    2. Enable the podman.socket service by running this command: 
      systemctl enable --now podman.socket
    3. Install Podman Compose by running these commands: 
      curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
    4. Verify that the podman.socket service is active and that Podman Compose is available by running these commands: 
      systemctl status podman.socket
podman compose -v
    5. Update Podman configuration to ensure that the function-as-a-service (FaaS) integration can be used after the remote worker is installed.
      1. Create and edit a new Podman configuration file by running this command: 
        vi /etc/containers/registries.conf.d/<file-name>.conf
        Replace <file-name> with a file name of your choosing.
      2. In the new file, add the following configuration: 
        [[registry]]
location = "<CW-FQDN>"
insecure = true
        • Replace <CW-FQDN> with the fully qualified domain name (FQDN) of the host where Concert Workflows runs, for example, my-cw-host.example.com.
        • By adding this configuration, you ensure that the internal FaaS registry trusts the FQDN of this host.
      3. Restart Podman by running this command: 
        systemctl restart podman
Procedure
  1. Download the stand-alone installation package for x86 architecture by clicking this link.
  2. Copy the remote worker installation package to your VM file system.
  3. Extract the package by running this command: 
    tar xfz ibm-concert-workflows-rw-x86_64.tar.gz
  4. Go to the folder that contains the remote worker installation script by running this command: 
    cd ./ibm-concert-workflows-rw
  5. Install the remote worker by running this command: 
    ./bin/install_rw.sh \
--license-acceptance=y \
--server-hostname=<CW_server_hostname> \
--worker-group-name=<worker_group_name> \
--worker-group-secret-key=<worker_group_secret> \
--target-platform=<podman|docker>
    • Replace <CW_server_hostname> with the highlighted Concert Workflows server hostname that you took note of when you created the worker group. To see this host name again, open the Concert Workflows UI, click Worker groups in the sidebar, and open the group that you created. The host name is highlighted in the dialog.
    • Replace <worker_group_name> with the name of the worker group that you created.
    • Replace <worker_group_secret> with the value of the new group’s secret.
    • If your container runtime is Docker, specify docker as the target-platform parameter value. If you are using Podman, specify podman.

Now, when you create a workflow, you can use the new worker group to run it by clicking the Start block in the workflow editor and selecting the new group.

Installing on a Kubernetes cluster

You can use this method to install a remote worker on an OpenShift Container Platform (OCP) or Amazon Elastic Kubernetes Service (EKS) cluster.

Prerequisites
  • Log in to the remote host as a user with root privileges and run all commands as this root user.
  • If you intend to load the images from the embedded file when you install the remote worker, you must set up a private image registry on the remote host. For more information about using private registries with Kubernetes clusters, see Using a private registry.
  • Consider your cluster storage configuration:
    • On the cluster, ensure that at least one storage class is specified and marked as the default storage class. For OCP clusters, see Storage.
    • You can configure custom storage for Concert Workflows by specifying a global storage class or by specifying per-component overrides.
      Attention: Some custom storage options, such as using your own external repositories or configuring per-component storage, must be configured before beginning the installation process.
  • Install and configure Helm version 3.x by running these commands: 
    curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
  • If you intend to install the remote worker on an OCP cluster and the cluster is not already created, complete these tasks:
    • Install Red Hat OpenShift Container Platform 4.14.0 (or a later version). For more information, refer to Installation documentation for OpenShift Container Platform.
    • Install the Red Hat OpenShift Container Platform command-line interface oc. Install the version that matches your installed version of Red Hat OpenShift Container Platform. For more information, refer to Installing the OpenShift CLI.
    • Log in to the OCP cluster by using the oc login command.
  • If you intend to install the remote worker on an EKS cluster, complete these tasks:
    • Ensure that the following tools are available:
      • AWS CLI
      • kubectl
      • eksctl
    • Ensure that you are logged in to the EKS cluster via kubectl.
Procedure
  1. Download the x86 installation package of your choosing.
    • To download the stand-alone package for x86 architecture, click this link.
    • To download the standard Concert package for x86 architecture, run this command: 
      wget https://github.com/IBM/Concert/releases/download/v3.0.0/ibm-concert-x86.tar.gz
  2. Copy the package to your VM file system.
  3. Extract the package.
    • For the stand-alone x86 package, run this command: 
      tar xfz ibm-concert-workflows-rw-x86_64.tar.gz
    • For the standard Concert x86 package, run this command: 
      tar xfz ibm-concert-x86.tar.gz
  4. If you want to load the required images from IBM Container Registry, ensure that your IBM entitlement key will be used as the registry password by running this command: 
    export IBM_REG_PASS=<your-entitlement-key>
    Replace <your-entitlement-key> with your IBM entitlement key.
  5. Go to the folder that contains the remote worker installation script.
    • For stand-alone packages, run this command: 
      cd ./ibm-concert-workflows-rw
    • For standard Concert packages, run this command: 
      cd ./ibm-concert/ibm-concert-k8s-workflows
  6. If you downloaded a stand-alone package, and you want to load the images from the embedded file when you install, extract them into your private registry by running this command: 
    ./bin/adm/cw-img-mgmt.sh --load-images \
 --tgt-registry=<private_registry_URL> \
 --tgt-registry-user=<private_registry_username> \
 --tgt-registry-password=<private_registry_password>
    • Replace <private_registry_URL> with your private registry’s URL (for example, tokyo1.fyre.ibm.com:5000).
    • Replace <private_registry_username> and <private_registry_password> with your private registry credentials.
  7. Install the remote worker by running this command: 
    ./bin/install_rw.sh \
--license-acceptance=y \
--server-hostname=<CW_server_hostname> \
--worker-group-name=<worker_group_name> \
--worker-group-secret-key=<worker_group_secret> \
--target-platform=k8s \
--registry=<registry_URL> \
--registry-user=<registry_username> \
--registry-password=<registry_password>
    • Replace <CW_server_hostname> with the highlighted Concert Workflows server hostname that you took note of when you created the worker group. To see this host name again, open the Concert Workflows UI, click Worker groups in the sidebar, and open the group that you created. The host name is highlighted in the dialog.
    • Replace <worker_group_name> with the name of the worker group that you created.
    • Replace <worker_group_secret> with the value of the new group’s secret.
    • Replace <registry_URL> with either your private registry’s URL (for example, tokyo1.fyre.ibm.com:5000) or cp.icr.io (to access IBM Container Registry).
    • Replace <registry_username> with either your private registry username or cp (to access IBM Container Registry).
    • Replace <registry_password> with either your private registry password or $IBM_REG_PASS (to access IBM Container Registry).
  8. Use the kubectl get pods command to monitor the pod statuses. When the pliant-worker pod is running, the remote worker is installed successfully.

Now, when you create a workflow, you can use the new worker group to run it by clicking the Start block in the workflow editor and selecting the new group.

Connecting to a different worker group or Concert Workflows instance

After you install a remote worker, you cannot update its configuration to connect it to a different worker group or Concert Workflows instance. To connect to another group or instance, complete the following steps:
  1. Uninstall the remote worker by deleting the namespace where it is installed. Run the following command: 
    kubectl delete namespace <installation-namespace>
    Replace <installation-namespace> with the namespace where the remote worker is installed.
  2. Reinstall the remote worker and provide the details of the Concert Workflows instance and worker group that you want to connect it to.

Troubleshooting

If the remote worker pod (pliant-worker) does not appear, or does not start, complete the following steps:
  • Verify that the server host name value that you provided for the --server-hostname parameter is correct. To see the correct host name to use, go to the Concert Workflows UI, click Worker groups in the sidebar, and open the group that you created. The host name is highlighted in the dialog.
  • If you used IBM Container Registry as the image source when you installed the remote worker, confirm that your IBM entitlement key is valid. For more information, see Obtaining an IBM entitlement API key.
  • If you used a registry (either IBM Container Registry or a private registry) as the image source, check that you provided the correct values for the --registry, --registry-user, and --registry-password parameters.
    • For IBM Container Registry, the --registry value must be cp.icr.io, the --registry-user value must be cp, and the --registry-password must be a valid IBM entitlement key.
  • Review the logs for the remote worker pod by running this command: 
    kubectl logs <pliant-worker>