Example of Application Team Implementation

The following series of steps describe an example of end-to-end setup and usage of Control-M for Kubernetes by the Finance Application team. In this example, the Application team deploys Agents into their own namespace using a container image and a Helm chart locally.

1. Obtain the Control-M/Agent container image and store it in your internal repository:
   1. Pull the latest Control-M/Agent container image that includes Java (for example, 9.21.310-k8s-openjdk) from the controlm/helix-agent repository in the Docker Hub.
   2. Push the image into your internal repository, local.repo
   3. Prepare a secret in the Kubernetes cluster to store your repository credentials, as described in the Kubernetes documentation.
      In our example, this secret is named regcred
2. Download the Control-M for Kubernetes Helm chart to the machine where you plan to run the Helm installation, using the following command:
   wget https://controlm-charts.s3.us-west-2.amazonaws.com/helix-controlm-agent-9.21.310.tgz 
   In our example, this .tgz file is stored in /home/helm
3. Assign the required privileges to the Agent to run Kubernetes jobs.
   To do this, ask your Kubernetes cluster administrator to allocate a Service Account for the Control-M/Agent, as described in Service-Account-Privileges.
4. Ensure that job data and Agent state are kept during pod restarts, by preparing a persistent volume that the Agents use for storage.
   Ask your cluster administrator to prepare the persistent volume, as described in Persistent-Storage.
   In our example, we use an EKS cluster on AWS with an efs-sc storage class.

1. Generate an Agent token associated with an Agent tag. For more information, see Agent Token Management.
   In our example, the Agent token is associated with an Agent tag named finance.
   
2. Enable running jobs to multiple Agents that are grouped in a Host Group, by granting authorizations for registering Agents and creating a Host group that are associated to a specific tag.
   Ask your Control-M Administrator to set up a role with access to the Agents and Host Group.
   In the following image, FULL access is granted to the Host Group and Agents with the finance tag:
   

1. Enable the Agent container to use the authorizations created in the previous step, by creating an API token associated with this role.
   The token is used to connect to the Automation API endpoint and run the APIs for registering Agents and adding them to a host group.
   Ask your Control-M Administrator to generate an API token associated with the same role as in the previous step.
   For more information, see Creating an API Token.
   For extra security, in this example the API token is contained within a Kubernetes secret named finance_secret. To create this secret, use the following command:
   kubectl create secret generic finance_secret --from-literal='apiToken=<apiToken>'

1. Ask your Control-M Administrator for the following details, which you need for input parameters when you install the Helm chart in the next step:
   • Control-M Automation API endpoint
   • Control-M/Server name

2. Run the Helm chart to deploy your Agents into a hostgroup named finance_hostgroup:

   helm install FinanceRelease /home/helm/helix-controlm-agent-9.21.310.tgz --version 9.21.310 --namespace=finance_ns \
   --set image.repo=local.repo --set image.pullSecrets"[0]".name=regcred \
   --set server.name=IN01  \
   --set api.endpoint=https://controlm-tenant-aapi.us2.controlm.com/automation-api \
   --set api.secret=finance_secret --set pvc.storageClass=efs-sc  --set agent.tag=finance \
   --set pod.serviceAccount.create=false --set pod.serviceAccount.name=finance_service_account \
   --set server.hostgroup=finance_hostgroup
   

   For more information, see Deploying-Agents-Using-a-Helm-Chart.

3. Once your Agents are up and running, define and deploy a centralized connection profile through Automation API.

   1. Define the centralized connection profile in a JSON definitions file, FIN_CCP.json:

      {
        "FIN_CCP": {
           "Type": "ConnectionProfile:Kubernetes",
           "Description": "Profile for Agent running in the Finance namespace",
           "Namespace": "finance_ns",
           "Centralized": true
         }
      }

      For more information, see ConnectionProfile:Kubernetes in the Control-M Automation API documentation.

   2. Deploy the definitions file using the deploy command:

      ctm deploy FIN_CCP.json

   Note

   Alternatively, you can create the centralized connection profile through Control-M Web, as described in Creating a Centralized Connection Profile and Kubernetes Connection Profile Parameters.

4. Define a Kubernetes job through Automation API.

   1. Obtain the application job YAML file:
      

      apiVersion: batch/v1
      kind: Job
      metadata:
        name: {{job_yaml_file_params:jobname}}
      spec:
        template:
          spec:
            nodeSelector:
              kubernetes.io/os: linux
            containers:
           - name: busybox0
              image: busybox
              command: ["echo",  "Hello {{job_yaml_file_params:subject}}"]
            restartPolicy: Never
        backoffLimit: 4

   2. Convert the YAML code to JSON format for inclusion in the JSON job definitions (see the Job Spec Yaml parameter in the next step).
      You can use the JQ command on Linux to convert the YAML file to JSON.
      

   3. Define your job in a JSON definitions file, FIN_JOB.json:

      {
          "Finance_Folder": {
              "Type": "Folder",
              "ControlmServer": "ctmServer1",
              "Description": "Test Kubernetes Job",
              "OrderMethod": "Manual",
              "Kubernetes_Job": {
                  "Type": "Job:Kubernetes",
                  "ConnectionProfile": "FIN_CCP",
                  "Description": "Test K job",
                  "Host": "finance_hostgroup",
                  "Job Spec Yaml" : "apiVersion: batch/v1\nkind: Job\nmetadata:\n  name: {{job_yaml_file_params:jobname}}\nspec:\n  template:\n    spec:\n      nodeSelector:\n        kubernetes.io/os: linux\n      containers:\n      - name: busybox0\n        image: busybox\n        command: [\"echo\",  \"Hello {{job_yaml_file_params:subject}}\"]\n      restartPolicy: Never\n  backoffLimit: 4\n",
                  "Job Spec Parameters" : "{\"jobname\":\"ctmjob-%%ORDERID\",\"subject\":\"Finance Department\"}",
                  "Get Pod Logs": "Get Logs",
                  "Job Cleanup": "Delete Job",
                  "Job Status Polling Interval": "20"
              }
          }
      }

      For more information, see Job:Kubernetes in the Control-M Automation API documentation.
      The %%ORDERID variable in the jobname (defined by Job Spec Parameters) creates a unique Kubernetes jobname for each job run, which enables concurrent execution of multiple job runs.

   4. Deploy and run the folder and job using the run command:
      

      ctm run FIN_JOB.json

      The Kubernetes job runs in your cluster and you can monitor its progress and view its output in Control-M.

   Note

   Alternatively, you can create and run the job through Control-M Web. See Creating a Job and Kubernetes Job parameters.