Configuring and Deploying Containerized Kubernetes Agents

Containerized Agents offer several advantages, including a more streamlined cloud integration and an "agentless" experience for Automic SaaS users. You can easily adopt these pre-configured Agents or integrate them into other Clients.

Containerized Agents come preconfigured and ready for immediate use; therefore, you avoid the need to install your Agents manually. The container-based Agents use Kubernetes and Helm Charts and can be stored in any cloud and deployed to be used either for an on-premises Automic Automation system, an Automic Automation Kubernetes Edition, or an Automic SaaS environment.

This topic guides you through the prerequisites, configuration, and deployment process for a containerized Kubernetes agent in an AE system without using authentication. If you want to use one of the methods that are available for authenticating the Agent, you must follow additional installation steps. For more information, see Agent Authentication in the Automic Automation documentation.

This page includes the following:

Prerequisites

To install and run a containerized Agent successfully, make sure you fulfill the requirements.

To deploy a container-based Agent, you require Kubernetes and Helm. Use the compatibility matrix to find the relevant information on supported versions, setup, or prerequisites. Check all CA Automic components and prerequisites for vendor, version, or setup information, and see the compatibility matrix. For more information, see the Compatibility Information.

Important! Scaling a containerized Agent deployment is not possible; therefore, you need one Helm installation per Agent installation. Make sure each Agent installation name is unique.

Downloading the Agent Offering

You can download the Agent Helm Chart offering from https://downloads.automic.com/, where you can also see the complete content of the offering.

To download the offering, follow these steps:

  1. Log in to https://downloads.automic.com/ with your Broadcom credentials and select the Agent component.

    On the offering download page, request access to the Automic public Docker registry.

  2. Once you have access to your company's GCP Service account, download the automic-image-pull-secret.json file and create the secret with the command provided.

    This allows your container platform to pull images from our password-protected repository. The following parameters are relevant:

    • Repository: Specifies the Docker image repository.

    • Tag: Defines the specific tag of the image to be used, for example, 24.2.0.

    • pullPolicy: Determines when Kubernetes should pull the image. Common values are Always, IfNotPresent, or Never.

    • pullSecret: (Optional) The name of the Kubernetes secret used to authorize pulling the image from a private registry.

    Example 

    image:
  repository: <path to agent repository>
  tag: "24.2.0"
  pullPolicy: Always
  pullSecret: automic-image-pull-secret

The offering zip file includes the Agent Helm Chart, as well as the values.yaml file that you can use to customize the Agent deployment/installation. For example, you can define the name of the configmap, INI file, the Agent authentication secret, and so on.

Configuring Kubernetes-Specific Components before Deploying the Kubernetes Agent

There are a number of settings specific to Kubernetes that you must or can define before the installation.

Note: You can make changes to the configuration after deployment. These changes require upgrading the Agent container.

For more information, see Upgrading Containerized Agents.

Containerized Agent Sizing, Requests, and Limits

Make sure you have considered all sizing requirements and that you have defined all necessary requests and limits to define the resources allocated to each Agent pod. For more information, see Sizing of AAKE in the Automic Automation documentation.

Preparing TLS/SSL Certificates

In an on-premises environment, the Agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners. In AAKE, these Agents establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure you have all the required certificates for the TLS/SSL communication in place. For more information, see the following topics in the Automic Automation documentation:

Annotations and Labels

In Kubernetes, you can enhance the visibility and control of your resources by setting annotations and labels for deployment and pods directly in the values.yaml file. Once configured, these annotations and labels are automatically applied to the Kubernetes objects created, allowing you to add meaningful metadata, which improves resource management and boosts interoperability, enabling more efficient filtering and organization of your system.

Example

This example shows how to add annotations and labels for both, the deployment and the pod.

deployment:
  annotations:
    example.com/environment: "production" 
  labels:
    tier: "frontend"

pod:
  annotations:
    example.com/environment: "production" 
  labels:
    tier: "frontend"

Configuring the Containerized Agent before Deployment

There are a number of settings that you must or can define before the installation.

Important! When configuring containers, take into account that on-disk files are ephemeral. They are lost when containers or pods stop and restart. To store and refer to resources in the cluster (for example, to files, such as logs, traces, images, and so on), you must first define the names of the corresponding Persistent Volumes (PVs) and Persistent Volume Claims (PVCs) in the respective sections of the values.yaml file. All files that are written to other folders besides the ones that can be configured as PVCs are not persistent and will be lost after a pod restart.

For more information about Volumes in Kubernetes, please refer to the official Kubernetes product documentation.

Note: You can make changes to the configuration after deployment. These changes require upgrading the Agent container.

For more information, see Upgrading Containerized Agents.

Configuring the Agent Settings

The Agents are configured by the ucxcitx.ini file. You can configure the Agent settings using environment variables or a full INI file. Regardless of the option you choose, they are stored in the configmap.

Specifying a configMap for the Agent to Use Environment Variables

Yes, you can use environment variables to configure containerized Agents. To do so, you must create a configmap for the settings. This option gives you the flexibility of configuring individual parameters while keeping others with default values.

If you use this option, make sure you define the name of the configmap using the iniConfiguration.name parameter in the values.yaml file before deployment.

Each environment variable for containerized Agents follows a specific naming pattern: AUTOMIC_SECTIONNAME_KEYNAME:DEFINITION

  • PREFIX: AUTOMIC

    This is the prefix for all INI settings.

  • SECTIONNAME:

    Corresponds to the section name in the INI file, and it is defined in uppercase, without square brackets.

  • KEYNAME:

    Corresponds to the actual property name in the INI file of the Agent, and it is defined in uppercase. Stop characters, such as dots or slashes, are removed.

  • DEFINITION:

    The value that you want to define for the key.

Note: You can only use environment variables to change INI settings that were defined using environment variables. You cannot use them to change values that are commented out.

Examples

To change the TCP/IP parameter in the [TRACE] section of the INI file, use the environment variable AUTOMIC_TRACE_TCPIP.

This example shows how to use kubectl to create a configmap setting the AUTOMIC_GLOBAL_NAME, AUTOMIC_GLOBAL_SYSTEM, and AUTOMIC_TCPIP_CONNECTION environment variables for the Kubernetes Agent Integration.

kubectl create configmap ig-k8s-config \
    --from-literal=AUTOMIC_GLOBAL_NAME=IG_K8S \
    --from-literal=AUTOMIC_GLOBAL_SYSTEM=AUTOMIC \
    --from-literal=AUTOMIC_TCPIP_CONNECTION=jcp-ws:8443

Resulting configmap example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ig-k8s-config
data:
  AUTOMIC_GLOBAL_NAME: IG_K8S
  AUTOMIC_GLOBAL_SYSTEM: AUTOMIC
  AUTOMIC_TCPIP_CONNECTION: jcp-ws:8443

Specifying a configMap for the Agent to Use a Full INI File

Alternatively, you use a full Agent INI file that is stored as a multi-line key/value pair within a configmap, which is then mounted as a file to be used by the Agent. This option gives you the flexibility of defining all settings at once by copying and pasting the file content.

If you decide to use this option, make sure you specify the name of the configmap using the iniConfiguration.name parameter and the multi-line key using the iniConfiguration.ini parameter in the values.yaml file before deployment:

Example:

iniConfiguration:

name: ig-k8s-config

ini: ucxjcitx.ini

Have in mind that configuring the Agent requires the following:

  • name: Name of the Agent (or proxy agent)

    Max. allowed characters: 32

    Characters allowed: A-Z, 0-9, _, ., $, @, -, and #. Hyphens ("-") are only allowed in Agent names, and cannot be used in the names of any other objects.

  • system:AE system name

    Max. allowed characters: 8

    Characters allowed: Upper-case letters A to Z, numbers, and underscores ("_").

When you create a configmap from the INI file, you can deploy the configmap with the following command:

kubectl apply -f dev/configmap_env.yam

Example 

apiVersion: v1
kind: ConfigMap
metadata:
  name: ig-k8s-config
data:
  ucxjcitx.ini: |
    [GLOBAL]
    name=IG_K8S
    system=AUTOMIC
    ...

Creating the Agent Authentication Secret

You need to create a secret for the Agent authentication in the values.yaml file using the agentAuthentication.secretName key before the Agent deployment. The secret requires you to set the secretName and secretKeys. The secretKeys require a keyPassword, which secures the private key generated by the Agent upon starting and connecting to the Automation Engine.

Also, if you use the authentication methods LOCAL or LOCAL_REMOTE, you require an authentication package for the initial start, and need to set the initialPackage in the values.yaml file. For more information, see Agent Authentication in the Automic Automation documentation.

Example

This example creates an Agent authentication secret for a Kubernetes Agent integration, including the authentication package for the initial start.

kubectl create secret generic ig-k8s-secret  \
    --from-literal=keyPassword=changeit \
    --from-file=initialPackage=/tmp/ig-k8s/initialPackage

Important! Please note that, depending on the Agent that you want to use, you might need to add agent-specific configurations, which may require additional secrets.

The secret is set in the values.yaml file:

agentAuthentication:
  secretName: ig-k8s-secret
  secretKeys:
    keyPassword: keyPassword
    initialPackage: initialPackage

Adding Additional Trusted Certificates

If you use self-signed certificates, you need to store them in a folder for trusted certificates. To do so, you have two options:

  • Use a PVC

    Store the trusted certificates on a volume and define the PVC name using the trustedCertificates parameter in the values.yaml file, for example:

    trustedCertificates:
  pvc: ig-k8s-trustedcert-pvc

  • Create a secret

    Store them in a secret that will be mounted in the /opt/<agent>/bin/trustedcert directory. You can define the secret name using the trustedCertificates.secretName and the keys using the trustedCertificates.secretKeys parameters in the values.yaml file. Each key is mounted as a file, where the key name matches the file name. For example:

    trustedCertificates:
  pvc: <agent>-trustedcert-pvc
  secretName: <agent>-trustedcert
  secretKeys:
    - tls.crt
    - rest-service.pem

Setting the Security Folder

You must set a volume for the security folder where the Agent stores security-related files like the private key, signed certificate, and root certificate. To do so, you need to define the names of the corresponding Persistent Volumes (PVs) and Persistent Volume Claims (PVCs) to be used for mounting the security folder in the securityFolder.pvc sections of the values.yaml file.

Example 

securityFolder:
  pvc: <agent>-security-pvc

Setting Logs and Traces

You can define the file to which the Agents should write their activities (logs and traces). To do so, you need to define the relevant names of the corresponding Persistent Volume Claims (PVCs) in the logging and tracing section of values.yaml file. This allows the logs and job reports, as well as the traces, if activated, to be written to the files that you have defined.

Example 

logging:
  pvc: ig-k8s-temp-pvc

tracing:
  pvc: ig-k8s-trace-pvc

The log files generated by the Agent are stored in the /opt/ig-k8s/temp/ folder; therefore, to make the logging output accessible outside the pod, you have to configure the volume for the temp folder.

The trace files generated by the Agent are stored in the /opt/ig-k8s/trace/ file. If you want to use a separate volume for the traces, you can do so. Make sure that the file parameter of the [TRACE] section of the Agent's INI file points to files in the folder /opt/ig-k8s/trace/. For example:

file=/opt/ig-k8s/trace/ra_trace_##.txt

In both cases (logging and tracing), the PVC used should provide write permissions for the relevant User.

Setting the Data Folder

You need to have a volume where you can store job definition files. The data.pvc in the values.yaml file defines the name of the PVC, and data.path defines mount folder. The required PVC name is ig-k8s-data-pvc. For example:

path= /opt/ig-k8s/data

Using the Authentication Token from File in Connection Object

If you are using an authentication method which requires files on the agent's file system, you have to store them in a secret and mention them here. The keys in the secret will be mounted as files in the directory /opt/ig-k8s/bin/fileauthentication. After that these files can referenced in the Kubernetes Connection object.

fileauthentication:
  secretName: ig-k8s-credentials 
  secretKeys:
    - credentials

For example:

/opt/ig-k8s/bin/fileauthentication/credentials

Notes:

  • You can skip this step if you use a direct token.

  • Command to create the secret:

    kubectl create secret generic ig-k8s-credentials --from-file=credentials=/opt/k8s/token.txt

Deploying Containerized Agents

Once you have covered all prerequisites and you have configured both Kubernetes and the Agent, you can trigger the Helm chart installation.

helm install <installation name> <agent>.tgz -f values.yaml

  • Installation name: Name of the Helm installation, which you can choose freely.

  • Agent: Name of the Agent you are installing (including version)

  • -f values.yaml: Provides the Helm Chart configuration to be used.

Example

For example, this command installs the Kubernetes Agent Integration, version 24.2:

helm install ig-k8s ig-k8s-24.2.0 .tgz -f values.yaml

See also: