Co-Authors: Vincent Le, Scott Nguyen, Shubham Gurao.

Abstract

This blog focuses on implementing a production-ready deployment of IBM Cloud Pak for Business Automation (CP4BA) on the OpenShift Container Platform using ArgoCD. By leveraging ArgoCD, a powerful GitOps tool, we streamline the deployment process, ensuring efficiency and automation in continuous delivery. We will explore the key components of ArgoCD, how it works, and provide step-by-step instructions to integrate it into your CP4BA deployment. From generating Kubernetes manifests to creating ArgoCD applications and monitoring deployments, this guide equips you with the knowledge needed to effectively manage your CP4BA environment. The GitOps approach ensures that your deployment remains consistent with the desired state defined in your Git repository, enhancing both reliability and scalability.

"NOTE:  Only fresh deployment/installation is currently supported.  Patching (applying iFixes) to the current version is also supported (e.g., current version is v24.0.0-IF002 and applying v24.0.0-IF005), but upgrade from a major version to the next major version (e.g., current version is v24.0.0-IF002 and upgrading to v25.0.0 GA) is not supported."

Introduction

IBM Cloud Pak for Business Automation helps automate business operations through an integrated platform of automation capabilities. The platform relies on OpenShift Container Platform, which makes it easier to configure, deploy, and manage containerized applications. Designed to support projects of all sizes (small and large), improve employee productivity, and deliver better end-to-end customer journeys while reducing the burden of governing your content and processes. By leveraging automation, it enables you to scale more effectively and accelerate work, driving better results faster.

What is ArgoCD ?

ArgoCD is a declarative continuous delivery tool for Kubernetes and OpenShift, based on the GitOps methodology. It ensures your application's deployment remains consistent with the desired state defined in your Git repository. Unlike traditional continuous delivery tools, ArgoCD can directly pull updated code from Git repositories and deploy it to Kubernetes resources.

How ArgoCD Works

ArgoCD embraces the GitOps model, using Git repositories as the definitive source for defining the desired state of applications. In this blog, we will focus on using plain YAML files, which provide a straightforward and clear method for managing deployments. This approach enables teams to easily version-control their configurations and collaborate efficiently.

ArgoCD automates the deployment of these desired application states across specified environments. It continuously monitors updates to branches, tags, or can be configured to deploy a specific version of manifests from a Git commit. By focusing on YAML files, this article aims to showcase a simple yet effective strategy for managing Kubernetes applications within a GitOps framework.

Setting Up GitOps with ArgoCD for IBM Cloud Pak for Business Automation

Integrating ArgoCD into your CP4BA deployment is essential for effectively managing Kubernetes resources. ArgoCD continuously monitors your Git configuration repository for changes and automatically applies the relevant Kubernetes resources to your cluster. This ensures that your CP4BA environment—encompassing pods, routes, and other components—stays up to date.

To deploy CP4BA using ArgoCD, follow these steps:

Prerequisites:

• Before beginning the deployment, ensure you have the following:

• A Red Hat OpenShift cluster set up and running.

• Dynamic storage provisioning enabled for the cluster see Storage considerations.

• Clone the public CP4BA Git repository to your bastion host or local machine. This repository contains the deployment artifacts in the appropriate branches for CP4BA.For example: 24.0.0-IF005 https://github.com/icp4a/CP4BA-with-ArgoCD/tree/24.0.0-IF005.

• Download the latest version by selecting the appropriate branch for the cert-kubernetes repository. For example: 24.0.0-IF005 https://github.com/icp4a/cert-kubernetes/tree/24.0.0-IF005.

• Your own private Git repository that ArgoCD will use for deployment.

• Download ArgoCD CLI. See download link for more information.

Step 1: Install ArgoCD

1. Install Red Hat OpenShift GitOps from the Operator Hub.

2. Select Red Hat OpenShift GitOps from the installed operators list and click on the ArgoCD and check whether the status of the instance is available.

Step 2: Connect Git Repository to ArgoCD

1. Access ArgoCD UI:

• To access the ArgoCD user interface, navigate to Networking → Routes → openshift-gitops-server in the project where the ArgoCD instance is installed.

• Click on the route URL to open the ArgoCD user interface. 

2. Log in to ArgoCD: 

• username :admin

• password: Retrieve the password from the openshift-gitops-cluster secret in the project where the ArgoCD instance is installed. 

3. Create custom Appproject: (Optional – only if you want to create a custom ArgoCD project):

   • Navigate to the prerequisites/ folder in the public Git repository: https://github.com/icp4a/CP4BA-with-ArgoCD/tree/24.0.0/prerequisites.

   • Open the appproject.yaml file and update the name: parameter to match any custom project name of your choice.

• By default, ArgoCD uses the default project to manage applications. If you want to define and use a custom project (e.g., cp4ba), follow these steps:

 Apply the AppProject to your cluster:

oc apply -f prerequisites/appproject.yaml

Note: Make sure the project: parameter in both the parent and child ArgoCD application YAMLs is updated to reflect the same custom project name.

4. Add Your Git Repository:

• Connect your customized Git repository to the ArgoCD instance running in your cluster. In the ArgoCD UI, navigate to Settings → Repositories → + CONNECT REPO.

• Add your GitHub repository with the necessary credentials and select the desired Project from the dropdown. Once connected, ArgoCD will use the repository contents to create the corresponding resources in the cluster, keeping it in sync with any changes.

Step 3: Adding cluster to ArgoCD

In CLI, run the commands to add your cluster .

1. Login to ArgoCD using CLI.

argocd login <Host>

Here <Host> is the ArgoCD server endpoint. For OpenShift, you can get the host from the route of the openshift-gitops-server

username: admin

password: openshift-gitops-secret

      2. Log in to your OpenShift cluster.

oc login --token=<token> --server=--server=https://<cluster-ip>:<port>

Where the <token> is your API token for your user on the cluster, and <cluster-ip>:<port> is the IP address and port number of the cluster.

     3. Find the context name to the target cluster.

context=$(oc config current-context)

4. Add the cluster to ArgoCD.

argocd cluster add $context --name=<cluster name> #cluster name can be arbitrary string 

It is recommended that you set cluster name to something meaningful. Note that ArgoCD will not validate cluster connection until you deploy an app onto it.

5. Once the cluster is added, you can verify it using

argocd cluster list

The <SERVER> from the output should be used for creating the applications.

6. To generate a Base64-encoded string for the IBM Entitled Registry:

Run the following command, replacing <Your IBM Entitlement Key>

The configmap manifest is provided

echo -n '{
  "auths": {
      "cp.icr.io": {
          "username": "cp",
          "password": "Your IBM Entitlement Key",
          "email": "",
          "auth": ""
      }
  }
}' | base64 -w 0

Step 4: Creating ArgoCD Applications:

1. Clone the your private Git repository to your local machine: 

This is the same Git repository you configured in the ArgoCD UI in Step 2.4

git clone <repoURL>

Then copy the cp4ba-manifests folder, prerequisites folder and their sub-folders from the public git repository (https://github.com/icp4a/CP4BA-with-ArgoCD/) into your private Git repository.

Explore the high-level folder structure of the public Git repository:
Note: The directory structure in the screenshot contains a subset of files for a specific capability (pattern). The manifest files that you generated could contain more or a different subset of files depending on the capability or capabilities that you are deploying.

Review the yaml files in parentapplication and childapplication folder, and modify them accordingly. See below for more detail

1. ParentApplication:

• The parentapplication.yaml located in the parentapplication/ directory. This file acts as the central controller and creates all the applications listed in the childapplication/ directory. When the parent application is applied, ArgoCD automatically triggers the deployment of all listed applications.

• Key parameters in parentapplication.yaml:

  • repoURL: Update this parameter <repoURL> with your git repo URL where all the manifest files are stored.

  • path: The path is where the child application yaml file is located in your repository.

  • server: Indicates the OpenShift API server where the resources will be deployed. Update this parameter <SERVER> with your desired OpenShift API server URL. You can get this value by running the following command “argocd cluster list”

  • targetRevision: Change the <targetRevision> to the branch name associated to your Git repository that contains all the manifests.

  • project: In step 2.3, if you have used different project make sure to update the project: parameter in the parent application YAML accordingly.

2. ChildApplication:

• The childapplication.yaml file creates all applications pointing to their corresponding directories and YAML manifest files. Each child application has parameters like repoURL, path, and server to specify where the resources will be deployed.

• Key parameters in childapplications:

  • repoURL: Update this parameter <repoURL> with your git repo URL where all the manifest files are stored.

  • path: The path should point to the directory in your Git repository that contains the YAML files for that specific resource .

  • server: Indicates the OpenShift API server where the resources will be deployed. Update this parameter <SERVER> with your desired OpenShift API server URL. You can get the server info by running the following command “argocd cluster list”.

  • targetRevision: Change the <targetRevision> to the branch name associated to your Git repository that contains all the manifests.

  • project: In step 2, if you have used different project make sure to update the project: parameter in the child application YAML accordingly

Update the parentapplication.yaml and childapplication.yaml files with the necessary changes.

Step 5: Generate Manifest Files

1. Creating operator-related resources:

To set up the necessary operator-related resources for CP4BA, simply copy the required manifest YAML files into your own Git repository. These include the namespace, catalogsources, secrets, configmaps, operator groups, and subscriptions.

If you are deploying using Separation of duties deployment, copy the content from the following folder.

• prerequisites/separation_of_duties/configmap
• prerequisites/separation_of_duties/namespace
• prerequisites/separation_of_duties/nss
• prerequisites/separation_of_duties/rbac

to the following folders respectively

• cp4ba-manifests/configmap
• cp4ba-manifests/namespace
• cp4ba-manifests/nss
• cp4ba-manifests/rbac

Below is the sample command to copy the files

for dir in configmap namespace nss rbac; do
  cp -r prerequisites/separation_of_duties/$dir/* cp4ba-manifests/$dir/
done

Note that for separation of duties deployment, "cp4ba-project" is the namespace for the operator and "cp4ba-operand" is the namespace for the operand in this deployment. You may change them accordingly.

• Namespace: The namespace manifest is located at cp4ba-manifests/namespace/namespace.yaml. Replace cp4ba-project with the namespace where you intend to deploy CP4BA (In this blog we used “cp4ba-project”). For separation of duties, "cp4ba-project" will be the namespace for the operators and "cp4ba-operand" will be the namespace for the operands.

• Catalog Sources: Obtain the catalog_source.yaml from the https://github.com/icp4a/cert-kubernetes/ ( found in cert-kubernetes/descriptors/op-olm/catalog_source.yaml ). Copy the file into your repository at cp4ba-manifests/catalogsource/.

  • Note: There are 12 CatalogSource sections.

    • Replace all occurrences of openshift-marketplace namespace with your chosen namespace(eg: cp4ba-project)

    • For the Certificate Manager and License Manager catalogs, change the namespace from openshift-marketplace to ibm-cert-manager and ibm-licensing, respectively.

• Secrets: The ibm-entitlement-key secret can be found at cp4ba-manifests/secrets/ibm-entilement-key.yaml. Update <NAMESPACE> with your deployment namespace(eg: cp4ba-project) and replace the 

  <PASSWORD> placeholder with the value generated in step 3.6. For separation of duties deployment, use “cp4ba-operand” as the namespace.

• ConfigMap: The configmap manifest is provided at cp4ba-manifests/configmap/ibm-cp4ba-common-configmap.yaml. Update all the instances of cp4ba-project with your operator namespace. For the separation of duties deployment, the "metadata.namespace" and "data.services_namespace" point to the operand namespace(eg: cp4ba-operand), and the "data.operators_namespace" point to the operator namespace(eg: cp4ba-project)

• Operator Groups: The operator_group.yaml is located in https://github.com/icp4a/cert-kubernetes/ under cert-kubernetes/descriptors/op-olm/ directory . Copy it to cp4ba-manifests/operatorgroup/. Update the REPLACE_NAMESPACE placeholder with your chosen namespace (eg: cp4ba-project).

• Subscriptions: Get the subscription.yaml from the same directory in the cert-kubernetes repository and copy it to cp4ba-manifests/subscription/. Replace both REPLACE_NAMESPACE and openshift-marketplace with your CP4BA project namespace (eg: cp4ba-project). 

Important: Ensure that the namespace specified in all manifest files matches the namespace you are deploying to. This is crucial for the successful deployment of your CP4BA environment.

Push all the manifest YAML files into your own Git repository, organized with a clear directory structure. This setup enables ArgoCD to deploy the resources effectively.

2. Navigate to the parent directory:

• Change to the directory where the parentapplication.yaml file is located:

cd parentapplication/

3. Deploying the Parent Application:

• Apply the parentapplication.yaml by running the following command

oc apply -f parentapplication.yaml 

• ArgoCD will automatically create and deploy all the applications listed in the child applications. This means you don’t have to apply each child YAML file manually. The parent application handles the entire process for you, ensuring that all components are deployed in the correct order. Before following next step, verify if the CP4BA operator and other operators are installed successfully in your OCP cluster. Once the operators are successfully installed follow step 5.4.

4. Run cp4a-prerequisites.sh

The cp4a-prerequisites.sh script is located here : https://github.com/icp4a/cert-kubernetes/. The cp4a-prerequisites.sh script has three modes and running this script is necessary in order to generate SQL statement files (scripts) and YAML template files for the secrets based on the selected capabilities.

• Property Mode: The script in property mode generates the property files (DB/LDAP property files) with default values for database names, users, and schemas. Modify the generated DB/LDAP/user property files to match your infrastructure by adding your specific values for the database server name, database names, schemas, and LDAP details. These property files will be generated based on the capabilities selected while running cp4a-prerequisites.sh script.

• Generate Mode: In generate mode, the script takes the modified property files and generates the necessary database SQL statement files and YAML templates for secrets based on capabilities . The SQL statement files are used to create the required databases for CP4BA capabilities installation, while the YAML templates define the secrets, ensuring secure access to these databases during the deployment process.

  • Note: If EDB Postgres is not used, the generated SQL files must be executed manually by a DBA to create the required databases.

  • There is no need to run the create_secret.sh script - you can directly copy the generated YAML files from the secret_template folder to your manifests cp4ba-manifests/secrets/ folder.

For detailed instructions on running the script, you can refer to the IBM documentation: (https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/24.0.0?topic=pycc-recommended-preparing-databases-secrets-your-chosen-capabilities-by-running-script)

5. Run cp4a-deployment.sh

Executing this script is essential for preparing the final Custom Resource (CR) needed for deployment. It creates the Custom Resource that defines the configuration for your CP4BA instance. After running the script, copy the generated-cr to the cp4ba-manifests/deploycr/ directory. This organization allows for seamless deployment through ArgoCD, facilitating version control and consistent management of your deployment configuration. By placing the final CR manifest in the specified directory, you ensure that all changes are tracked and can be efficiently deployed across environments.

For more detailed information on the execution of the cp4a-deployment.sh script, please refer to the official documentation: https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/24.0.0?topic=cpd-option-1a-recommended-generating-custom-resource-deployment-script

Ensure that the generated secrets YAML files and the final Custom Resource (CR) are pushed to your GitHub repository, where ArgoCD can access them for deployment. After pushing the secrets YAML files and the final Custom Resource (CR) go to the ArgoCD UI, navigate to SYNC APPS → select SECRETS,CP4BACR applications → SYNC.

Step 6: Monitoring CP4BA Deployment with ArgoCD:

• Once the applications are created, monitor the deployment progress via the ArgoCD dashboard. This dashboard shows real-time synchronization status of each child application. As deployment progresses, ArgoCD ensures all resources—such as namespaces, secrets, operators, and custom resources—are deployed according to the manifests in your GitHub repository.

Step 7: Validation of CP4BA

To validate the readiness of your CP4BA deployment, use the post-installation script (cp4a-post-install.sh) found in the cert-kubernetes repository https://github.com/icp4a/cert-kubernetes/ . The script helps you to assess the readiness of your CP4BA deployment, and to retrieve and validate connection information to all its services.

The cert-kubernetes/scripts/cp4a-post-install.sh script has four modes for a production deployment type:

• precheck

• The precheck mode gets some basic information about the cluster, the console, and the client.

• status

• The status mode gets the status of all the components from the custom resource (Ready | Not Ready | Not Installed).

• console

• The console mode gets the console connection information from the URLs and credentials.

• probe

• The probe mode checks the readiness and health of the deployment endpoints.

The script can be run with the following options:

./cp4a-post-install.sh --help
   --precheck         This mode gives information about the cluster and the client.
   --status           This mode gives the status of the services of the deployment. 
   --console          This mode gives the service URLs of the consoles in the deployment. 
   --probe            This mode checks the readiness of the deployment endpoints. 

When you run the script in the status, console, or probe mode, the commands display information about the Cloud Pak for Business Automation version and interim fix number of the installed deployment. The output also includes the list of CP4BA capabilities that are installed.

Step 8: Uninstalling the CP4BA deployment

Delete the parent application first then delete the child applications. You can uninstall Cloud Pak resources and components from your platform deployment from the command line or from the OpenShift Container Platform (OCP) console. You can choose to also remove the data associated with the capability. For the detailed information please refer our official documentation: https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/24.0.0?topic=icmppd-uninstalling-capabilities

Patching (applying iFixes) CP4BA using ArgoCD, follow these steps:

This section demonstrates how to patch an existing CP4BA deployment from one iFix version to another using the GitOps approach. By updating the Git repository with the new CatalogSource and Subscription manifests, ArgoCD automatically reconciles the changes and upgrades the operators to the target iFix version.

Important: Applying iFixes within the same CP4BA release stream is supported (for example, upgrading from v24.0.0-IF005 to v24.0.0-IF009). Upgrading from one major release to another (for example, v24.0.0 to v25.0.0) is not supported through this process.

Step 1: Before upgrading

Before proceeding with the upgrade, ensure:

1. Ensure you take regular backups of any databases associated with the environment.
2. Ensure your operators are in a healthy state, before upgrading. 
   If one or more operators are failing, then it can prevent the system from completing an upgrade.
   It is recommended to check a few of the important CR statuses to ensure there are not failures and the statuses appear ready for the various installed components. Check the status of the following CRs when they exist:

3. oc get icp4acluster -o yaml
   oc get content -o yaml
   oc get foundation -o yaml

Step 2: Get the new Catalog Source

1. Navigate to the public cert-kubernetes repository for your target iFix version.  For example: 24.0.0-IF009 https://github.com/icp4a/cert-kubernetes/tree/24.0.0-IF009.

2. Locate the catalog_source.yaml file under cert-kubernetes/descriptors/op-olm/catalog_source.yaml

Step 3: Adding New Catalog Source to Your Private Git Repository

Create a new file named new_catalogsource.yaml in the cp4ba-manifests/catalogsource/ directory of your private Git repository. Copy the contents of the catalog_source.yaml file obtained in Step 2 into the newly created new_catalogsource.yaml file.

• Update all namespace references in the catalog source file:

1. • Replace all occurrences of openshift-marketplace with your chosen namespace (for example, cp4ba-project).

   • For the Certificate Manager and License Manager catalogs, change the namespace from openshift-marketplace to ibm-cert-manager and ibm-licensing, respectively.

Step 4: Update subscriptions manifest

The public git repository provides sample Subscription manifests under the ifix/subscriptions/ directory.

• Copy the Subscription manifest into the cp4ba-manifests/subscriptions/ directory:

cp -r ifix/subscriptions/* subscriptions/

• Update the following values in the Subscription YAML file:

• • Replace all occurrences of cp4ba-project in the Subscription manifest with your deployment namespace, including the values for metadata.name, metadata.namespace, and sourceNamespace.

  • Replace <new-catalog-name> with the catalog source name associated with the target iFix release.

After updating the CatalogSource and Subscription manifests, commit and push the changes to your private Git repository.

Step 5: Handling the StrimziPodSet Update

When patching to IBM Cloud Pak for Business Automation 24.0.0 IF007, 24.0.1 IF006, or 25.0.0 IF002, update the Kafka version annotation on the StrimziPodSet resource. This update ensures that the IBM Events operator can successfully reconcile the StrimziPodSet during the iFix patch.

• Set the namespace

OPER_NS=<operator-namespace> 
SERVICES_NS=<services-namespace

• Retrieve the IBM Events operator logs for reference.

EVENT_OPER_POD_NAME=$(oc get pods -n ${OPER_NS} | grep ibm-events-operator | grep -v catalog | awk '{print $1}')

oc logs -n ${OPER_NS} $EVENT_OPER_POD_NAME > ibm-events-operator_before_patch.log

• Retrieve the current StrimziPodSet resource.

oc get strimzipodsets.core.ibmevents.ibm.com iaf-system-kafka -n ${SERVICES_NS} -o yaml > StrimziPodSet_before_patch.yaml

• Retrieve the current Kafka version annotation.

KAFKA_VERSION=$(oc get strimzipodsets.core.ibmevents.ibm.com iaf-system-kafka -n ${SERVICES_NS} -o jsonpath='{.metadata.annotations.strimzi\.io/kafka-version}')

echo KAFKA_VERSION=$KAFKA_VERSION

Important: If no value is returned for KAFKA_VERSION,  do not continue. The StrimziPodSet resource must contain the strimzi.io/kafka-version annotation before applying the patch.

• Apply the patch to update the annotation name from "strimzi.io/kafka-version" to "ibmevents.ibm.com/kafka-version."

oc patch strimzipodsets.core.ibmevents.ibm.com iaf-system-kafka -n ${SERVICES_NS} --type=merge -p "{\"metadata\":{\"annotations\":{\"strimzi.io/kafka-version\":null,\"ibmevents.ibm.com/kafka-version\":\"$KAFKA_VERSION\"}}}"

• Get the strimzipodset again

oc get strimzipodsets.core.ibmevents.ibm.com iaf-system-kafka -n ${SERVICES_NS} -o yaml > StrimziPodSet_after_patch.yaml

• Wait a few minutes and periodically get the ibm-events-operator pod log again to check if reconcile can proceed normally to update the pods

oc logs -n ${OPER_NS} $EVENT_OPER_POD_NAME > ibm-events-operator_after_patch.log

Step 6: Monitor the upgrade

Wait for the operators to complete their upgrades.

By default all subscriptions are set to automatic, but if you have any subscriptions set to manual then you need to approve any pending InstallPlans.

Use the below command to see the current status of the install plans.

oc get installPlan

The upgrade will be blocked, if any of the needed InstallPlans are not approved. It is not recommended to set subscriptions to manual as this makes the upgrade more error prone.

Conclusion

In this blog, we walked through deploying IBM CP4BA using ArgoCD. This GitOps-based approach ensures that your CP4BA environment is always in sync with your desired state as defined in your Git repository. With ArgoCD’s powerful features like automated synchronization and self-healing, managing complex applications like CP4BA becomes more efficient and scalable.

#Featured-area-2-home