--- name: ContinuousDelivery-install_private_workers title: Installing Delivery Pipeline Private Workers description: Install and register a Delivery Pipeline Private Worker so that IBM Cloud® Continuous Delivery Development teams can use the private worker in their toolchain configuration. Developers can run workloads within the network scope of the private worker installation without any inbound network connectivity. last-updated: 2026-08-13 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/ContinuousDelivery?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Installing Delivery Pipeline Private Workers {: #install-private-workers} DevOps Insights will reach end of service and be discontinued on **August 31, 2026**. Continuous Delivery will be discontinued in the following regions on 12 February 2027: **au-syd**, **ca-tor**, **us-east**. Code Risk Analyzer will also be discontinued in all regions on that date. If a region has no active usage of these features, the features in that region may be discontinued earlier and stop accepting new instances. [Learn more](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-faq_region_feature_consolidation&format=markdown) {: important} Install and register a Delivery Pipeline Private Worker so that IBM Cloud® Continuous Delivery Development teams can use the private worker in their toolchain configuration. Developers can run workloads within the network scope of the private worker installation without any inbound network connectivity. {: shortdesc} The Delivery Pipeline uses public and private workers to run pipeline jobs. By default, pipeline jobs are run by using public workers on IBM-managed public shared infrastructure. Pipeline jobs can access resources only on the public network (both within and outside of IBM) and are limited to 60 minutes run time per job. In certain scenarios, your Delivery Pipeline might require access to internal or on-premises resources. In these situations, you can connect to and integrate a Delivery Pipeline Private Worker to run on your own Kubernetes infrastructure. The private worker agents that are installed on private clusters request data only from the IBM-hosted private worker service. The data flow is one way and originates only from the agent. ## Prerequisites {: #pw_install_prereqs} Before you install a private worker, make sure that you have an IBM Cloud® account to create authentication keys. You need the latest kubectl version that is installed on the Administrator's desktop computer. And you must also have a [Kubernetes cluster](https://cloud.ibm.com/kubernetes/clusters){: external} (version 1.15 or higher) with Administrative access to install a private worker. * Suggested Kubernetes cluster configurations: * IBM Cloud Kubernetes Service version 1.21 or higher to run workloads in isolation on IBM Cloud Public. * Red Hat® OpenShift® on IBM Cloud® version 4.9 or later. * Network access: * Inbound: Not required. * Outbound network access uses `(TCP:443)` where the region matches the delivery pipeline location and is either `au-syd` (Sydney, Australia), `eu-de` (Frankfurt, Germany), `eu-gb` (London, United Kingdom), `jp-tok` (Tokyo, Japan), `us-south` (Dallas, US), `us-east` (Washington DC, US), `br-sao` (Sao Paulo), or `ca-tor` (Toronto, CA). For example, for the Frankfurt region specify `https://private-worker-service.eu-de.devops.cloud.ibm.com (TCP:443)`. For network access to the global endpoint for API key validation, use `https://iam.cloud.ibm.com (TCP:443)`. * Permissions to pull images from icr.io. Private workers require the tekton-pipelines infrastructure and must be able to pull tekton-releases images from icr.io to complete the private worker installation. To pull images from the `icr.io` container registry, you might need to [define a specific Kubernetes ClusterImagePolicy](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-faq_pipeline_private_workers&interface=ui&format=markdown#pipeline_private_worker_image_policy). {: tip} Because private workers are not compatible with Red Hat OpenShift Pipelines, it is recommended that you do not install them on a cluster with Red Hat OpenShift pipelines. {: important} ## Installing a Delivery Pipeline Private Worker {: #install_pw} To install a private worker, you must have Administrator level access to a cluster. Private worker installation can be completed only by way of the command line since no graphical user interface is available. {: important} ### Installing the Delivery Pipeline Private Worker by using the CLI {: #install_pw_cli} {: cli} The following steps are intended for Administrators who are preparing environments and private workers for multiple people or teams. To install private workers for your own use, see [Setting up a Delivery Pipeline Private Worker](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-private-workers&format=markdown#set_up_private_worker). {: tip} #### Installing directly on a cluster {: #direct_install_pw_cli} {: cli} To install the framework directly on a cluster, you must have admin access to the cluster. From the IBM Cloud CLI, type the following command: ```text kubectl apply --filename "https://private-worker-service.{REGION}.devops.cloud.ibm.com/install" ``` Where `{REGION}` is the location of the toolchain's pipeline. You can specify any of the following values for the `{REGION}`: - `au-syd` (Sydney, Australia) - `eu-de` (Frankfurt, Germany) - `eu-gb` (London, United Kingdom) - `jp-tok` (Tokyo, Japan) - `us-south` (Dallas, US) - `us-east` (Washington DC, US) - `ca-tor` (Toronto, CA) - `br-sao` (Sao Paulo, Brazil) #### Installing directly on a firewalled cluster {: #firewall_install_pw_cli} {: cli} To install the framework directly on a cluster, you must have admin access to the cluster. From the IBM Cloud CLI, type the following command: ```text kubectl apply --filename "https://private-worker-service.{REGION}.devops.cloud.ibm.com/install?private=true" ``` Where `{REGION}` is the location of the toolchain's pipeline. You can specify any of the following values for the `{REGION}`: - `au-syd` (Sydney, Australia) - `eu-de` (Frankfurt, Germany) - `eu-gb` (London, United Kingdom) - `jp-tok` (Tokyo, Japan) - `us-south` (Dallas, US) - `us-east` (Washington DC, US) - `ca-tor` (Toronto, CA) - `br-sao` (Sao Paulo, Brazil) You must have a [VRF enabled](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint&interface=ui&format=markdown) IBM Cloud account to use this feature. {: important} It is possible to set up a pool of private workers by repeating this process on additional Kubernetes clusters. Load will be shared across all workers in the pool. {:tip } ## Registering a Delivery Pipeline Private Worker {: #register_pw} ### Creating a service ID {: #pw_create_service_id} A service ID represents a pool of one or more private workers that act together. You can initially register one private worker installation, and then incrementally register more private workers into the same group by reusing the same service ID. Registering multiple private workers in the same group supports higher availability and horizontal scaling of your private worker capacity. For more information about service IDs, see [Creating and working with service IDs](https://cloud.ibm.com/docs/iam?topic=iam-serviceids&interface=ui&format=markdown). #### Creating a service ID in the console {: #console_create_service_id} {: ui} 1. Log in to [IBM Cloud](http://cloud.ibm.com){: external}. 2. Go to [https://cloud.ibm.com/iam/serviceids](https://cloud.ibm.com/iam/serviceids){: external}. 3. Click **Create**. 4. Enter a name and description for the service ID. If you are creating a service ID for a pool of private workers, specify the name of the private workers pool, for example: **Pipeline Private Workers for Acme**. 5. Click **Create**. 6. Save your service ID for later use. The service ID is required on the Kubernetes cluster that is targeted for the Delivery Pipeline Private Worker installation. #### Creating a service ID by using the CLI {: #cli_create_service_id} {: cli} From the IBM Cloud CLI, type the following command: ```text $ ibmcloud iam service-id-create {worker-pool-name} -d "{worker-pool-description}" Creating service ID {worker-pool-name} bound to current account as username@domain.com...OK Service ID {worker-pool-name} is created successfully Name {worker-pool-name} Description {worker-pool-description} CRN crn:v1:bluemix:public:iam-identity::a/8d63fb1cc5e99e86dd7229dddff75fef::serviceid:ServiceId-38ffff31-3ea3-4ecc-9732-190f7a993097 Bound To crn:v1:bluemix:public:::a/8d63fb1cc5e99e86dd7229dddff75fef::: Version 1-6df15bde97b6e87f583a557f8731888f Locked false UUID ServiceId-38ffff31-3ea3-4ecc-9732-190f7a993097 ``` ### Creating an API key {: #pw_create_api_key} An API key is a unique code that is passed to an API to identify the application or user that is calling it. To prevent malicious use of an API, you can use API keys to track and control how that API is used. For more information about API keys, see [Understanding API keys](https://cloud.ibm.com/docs/iam?topic=iam-manapikey&format=markdown). #### Creating an API key in the console {: #console_create_key} {: ui} 1. Log in to [IBM Cloud](http://cloud.ibm.com){: external}. 2. Go to [https://cloud.ibm.com/iam/serviceids](https://cloud.ibm.com/iam/serviceids){: external}. 3. Select the Service ID that you want to create an API for. 4. In the **API keys** tab, click **Create**. 5. Enter a name and description for the API key to specify the private worker installation, such as **Pipeline Private Worker in IBM Cloud Private**. 6. Click **Create**. 7. Copy or download your API key. You cannot retrieve your API key again after you create it. #### Creating an API key by using the CLI {: #cli_create_key} {: cli} From the IBM Cloud CLI, type the following command: ```text $ ibmcloud iam service-api-key-create {worker-api-key-name} (SERVICE\_ID\_NAME|SERVICE\_ID\_UUID) \[-d, --description DESCRIPTION\] \[--file OUT_FILE\] Creating API key {worker-api-key-name} of service SERVICE\_ID\_NAME as username@domain.com... OK Service API key {worker-api-key-name} is created Successfully saved API key information to FILE Please preserve the API key! It cannot be retrieved after it's created. Name {worker-api-key-name} Description Description Bound To crn:v1:bluemix:public:iam-identity::a/2cac145ae78048679b129009cfe8c7f9::serviceid:ServiceId-9a6a14e5-5811-4c2c-9131-0e1d4bb7dfe1 Created At 2019-07-04T10:51+0000 API Key doJX9kORc4q5PRkH19H3lePDwYRAKNWk4XlIuEBrriOD Locked false UUID ApiKey-c1ee0fb5-90f2-476e-a260-a796e6d7f5f7 ``` ### Registering the private worker with IBM Cloud {: #pw_register_cloud} Before you can register the private worker with IBM Cloud, you must [deploy the private worker framework](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-install-private-workers&interface=cli&format=markdown#install_pw). To use the registration commands, you must be logged in to the Kubernetes cluster (with kubectl) into which you previously installed a private worker. {: tip} You must register a private worker with the specific IBM Cloud region that corresponds to the location of the delivery pipelines that you want to enable. 1. Specify a meaningful name for your private worker. This name must start and end with lowercase alphanumeric characters and can also contain `_` or `.` characters. 2. Run the following command with the service ID and API key that you created previously, the private worker name, and the `{REGION}` which is the location of the toolchain's pipeline. ```text $ kubectl create secret generic {WORKER_NAME}-auth -n default --from-literal=apikey={API_KEY} && kubectl apply --filename "https://private-worker-service.{REGION}.devops.cloud.ibm.com/install/worker?serviceId={SERVICE_ID}&name={WORKER_NAME}" workeragent.devops.cloud.ibm.com/worker-name created secret/worker-name-auth created ``` You can specify any of the following values for the `{REGION}`: * `au-syd` (Sydney, Australia) * `eu-de` (Frankfurt, Germany) * `eu-gb` (London, United Kingdom) * `jp-tok` (Tokyo, Japan) * `us-south` (Dallas, US) * `us-east` (Washington DC, US) * `ca-tor` (Toronto, CA) * `br-sao` (Sao Paulo, Brazil) {: tip} 3. To register an agent to use private endpoints use the optional `private` query parameter as follows: ```text $ kubectl create secret generic {WORKER_NAME}-auth -n default --from-literal=apikey={API_KEY} && kubectl apply --filename "https://private-worker-service.{REGION}.devops.cloud.ibm.com/install/worker?serviceId={SERVICE_ID}&name={WORKER_NAME}&private=true" ``` You must specify one of the following values for the `{REGION}`: * Frankfurt `eu-de` * London `eu-gb` * Dallas `us-south` * Washington DC `us-east` Note: The use of the `private` query parameter when registering an agent is required if the host cluster is in a firewalled environment {: important} 4. To verify that the agent is registered correctly, type the following command: ```text $ kubectl get workeragents NAME SERVICEID AGENT REGISTERED VERSION AUTH CONSTRAINED PAUSED OK Succeeded OK OK false false ``` The private workers are meant to be installed in the `default` namespace. They should never be installed in the `tekton-pipelines` namespace. This namespace is reserved for the Tekton framework and the agent deployment. Installing the worker agent in a different namespace than the `default` namespace can cause some unexpected side effects. {: tip} ## Configuring the Delivery Pipeline Private Worker to use private endpoints {: #install_pw_agent_pse} By default, private workers use public endpoints for communication. A cluster administrator can update the private worker configuration to use private endpoints so that communication between the private worker and the IBM Cloud® Continuous Delivery service does not use the public internet. 1. Get the name of the agent that is installed on the cluster: ```text kubectl get workeragents -n default ``` 2. Change the `apiUrl` for that agent: ```text kubectl patch workeragent {WORKER_NAME} --type='merge' -p '{"spec": {"apiUrl":"https://private-worker-service.private.{REGION}.devops.cloud.ibm.com"}}' ``` Where `{REGION}` is the location of the toolchain's pipeline. Private endpoints are available in the following regions: * Dallas `us-south` * Washington `us-east` * Frankfurt `eu-de` * London `eu-gb` You must have a [VRF enabled](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint&interface=ui&format=markdown) IBM Cloud account to use this feature. {: important} 3. Optional. To return to using public endpoints for the agent, type the following command: ```text kubectl patch workeragent {WORKER_NAME} -n default --type='merge' -p '{"spec": {"apiUrl":"https://private-worker-service.{REGION}.devops.cloud.ibm.com"}}' ``` ## Configuring the Delivery Pipeline Private Worker to use Satellite link endpoints {: #install_pw_agent_satellite} By default, private workers use public endpoints for communication. A cluster administrator can update the private worker configuration to use Satellite link endpoints so that communication between the private worker and the Continuous Delivery service goes through Satellite link endpoints. 1. [Create a cloud Satellite link endpoint](https://cloud.ibm.com/docs/satellite?topic=satellite-link-cloud-create&format=markdown) for the IBM Cloud® Continuous Delivery service and set `FQDN` and `Service indication name` to use the following value: ```text private-worker-service.{REGION}.devops.cloud.ibm.com ``` Where `{REGION}` is the location of the toolchain's pipeline. 2. Create a configmap in the private worker namespace that maps the public endpoints to the Satellite link endpoints: ```text apiVersion: v1 kind: ConfigMap metadata: name: pipelineworker-url-map data: iam.cloud.ibm.com: private-worker-service.{REGION}.devops.cloud.ibm.com: ``` You can add endpoints to the configmap, such as these [default Satellite link endpoints](https://cloud.ibm.com/docs/satellite?topic=satellite-default-link-endpoints&format=markdown). {: tip} ## Updating the Delivery Pipeline Private Worker installation {: #install_pw_update} If the private worker is reported as inactive, you must update the installation. To view the version of your private worker, type one of the following commands: * IBM Cloud Kubernetes Service: `kubectl -n tekton-pipelines describe deploy private-worker-agent | grep Image` * Red Hat® OpenShift® on IBM Cloud®: `kubectl -n openshift-operators describe deploy private-worker-agent-controller-manager | grep Image` To update your private worker installation, complete the following steps: 1. Run the [installation command](#install_pw) again. 2. [Register the private worker](#register_pw) on your Kubernetes cluster again. You can reuse the `apikey` that you used for the existing private worker. {: tip} For more information about Delivery Pipeline Private Workers, see [Troubleshooting for Delivery Pipeline Private Workers](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-troubleshoot-pipeline-private-workers&format=markdown#troubleshoot-pw-images) and [FAQs for Pipeline Private Workers](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-faq_pipeline_private_workers&interface=ui&format=markdown). {: tip}