Installing Delivery Pipeline Private Workers

Prerequisites

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 (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 Sydney (au-syd), Frankfurt (eu-de), London (eu-gb), Tokyo (jp-tok), Osaka (jp-osa), Dallas (us-south), Washington DC (us-east), Sao Paulo (br-sao), or Toronto (ca-tor). 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.

• Optional. If you want to install the private worker by using the Operator Lifecycle Manager (OLM), the OLM operator framework must be installed on your cluster. This framework is preinstalled by default on all Red Hat® OpenShift® on IBM Cloud® clusters.

  A previous version of the IBM Cloud Kubernetes Service was provided on clusters that were created before v1.23. To use OLM on an IBM Cloud Kubernetes Service cluster, you must first update the cluster to v1.23. Next, you must upgrade to a current version of OLM by uninstalling the previous version of OLM and reinstalling OLM.

  To uninstall the previous OLM framework from an IBM Cloud Kubernetes Service cluster, run the following commands:

  kubectl delete deployment -n ibm-system catalog-operator
  kubectl delete deployment -n ibm-system olm-operator
  kubectl delete crd operatorgroups.operators.coreos.com
  kubectl delete crd operators.operators.coreos.com
  kubectl delete crd subscriptions.operators.coreos.com
  kubectl delete crd catalogsources.operators.coreos.com
  kubectl delete crd clusterserviceversions.operators.coreos.com
  kubectl delete crd installplans.operators.coreos.com
  kubectl delete sa -n ibm-system olm-operator-serviceaccount
  kubectl delete clusterrole system:controller:operator-lifecycle-manager
  kubectl delete clusterrolebinding olm-operator-binding-ibm-system
  kubectl delete clusterrole aggregate-olm-edit
  kubectl delete clusterrole aggregate-olm-view
  

  For instructions about how to install the new OLM framework, see How do I install OLM?.

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.

Installing a Delivery Pipeline Private Worker

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.

kubectl apply --filename "https://private-worker-service.{REGION}.devops.cloud.ibm.com/install"

kubectl apply --filename "https://private-worker-service.{REGION}.devops.cloud.ibm.com/install?type=openshift&olm=true"

$ kubectl apply --filename "https://private-worker-service.us-south.devops.cloud.ibm.com/install?type=openshift&olm=true"
catalogsource.operators.coreos.com/private-worker-agent created
subscription.operators.coreos.com/private-agent-subscription created

kubectl apply --filename "https://private-worker-service.{REGION}.devops.cloud.ibm.com/install?type=iks&olm=true"

$ kubectl apply --filename "https://private-worker-service.us-south.devops.cloud.ibm.com/install?type=iks&olm=true"
catalogsource.operators.coreos.com/private-worker-agent created
catalogsource.operators.coreos.com/tekton-framework created
operatorgroup.operators.coreos.com/agent-operator-group created
subscription.operators.coreos.com/private-agent-subscription created

Registering a Delivery Pipeline Private Worker

$ 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

$ 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

Configuring the Delivery Pipeline Private Worker to use private endpoints

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:

   kubectl get workeragents -n default
   

2. Change the apiUrl for that agent:

   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 IBM Cloud account to use this feature.

3. Optional. To return to using public endpoints for the agent, type the following command:

   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

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 for the IBM Cloud® Continuous Delivery service and set FQDN and Service indication name to use the following value:

   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:

   apiVersion: v1
   kind: ConfigMap
   metadata:
      name: pipelineworker-url-map
   data:
      iam.cloud.ibm.com: <default IAM satellite link endpoint for your satellite location>
      private-worker-service.{REGION}.devops.cloud.ibm.com: <satellite link endpoint created in step 1)>
   

   You can add endpoints to the configmap, such as these default Satellite link endpoints.

Updating the Delivery Pipeline Private Worker installation

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 again.
2. Register the private worker on your Kubernetes cluster again.

You can reuse the apikey that you used for the existing private worker.

For more information about Delivery Pipeline Private Workers, see Troubleshooting for Delivery Pipeline Private Workers and FAQs for Pipeline Private Workers.