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.

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 24.0.0 branch for CP4BA. https://github.com/icp4a/CP4BA-with-ArgoCD/tree/24.0.0.

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

• 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):

   • 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:

     • 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.

 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-cluster 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> with your entitlement key. 

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 and its 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.

• 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”).

• 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.

    • 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 and replace the <PASSWORD> placeholder with the value generated in step 3.6.

• 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.

• 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.

• 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.

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

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